הנחיות לשילוב בתוך האפליקציה בתוכנית המבצעים החיצוניים

במדריך הזה מוסבר איך לשלב את ממשקי ה-API כדי לתמוך בהצעות חיצוניות באפליקציות ובאזורים שעומדים בדרישות. מידע נוסף על תוכנית המבצעים החיצוניים כולל דרישות הסף והיקף גיאוגרפי. בדרישות התוכנית.

הגדרה של ספריית החיובים ב-Play

כדי להשתמש בממשקי API של מבצעים חיצוניים: להוסיף את גרסה 6.2.1 ואילך של התלות של ספריית החיובים ב-Play לאפליקציה ל-Android. כדי לבצע העברה מגרסה קודמת, פועלים לפי לפי ההוראות שמפורטות במדריך להעברת נתונים (מיגרציה) לפני שמנסים להטמיע. ומבצעים חיצוניים.

חיבור ל-Google Play

השלבים הראשונים בתהליך השילוב זהים לשלבים שמתוארים כאן המדריך לשילוב של חיוב, עם כמה שינויים אתחול BillingClient:

  • עליך להפעיל method חדשה כדי לציין שברצונך להשתמש בהרשאה חיצונית מבצעים: enableExternalOffer.

הדוגמה הבאה ממחישה אתחול של BillingClient עם הערכים האלה שינויים:

Kotlin

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

לאחר האתחול של BillingClient, עליך ליצור חיבור אל Google Play כמו שמתואר במדריך ההטמעה.

בדיקת זמינות

האפליקציה צריכה לאשר מבצעים חיצוניים זמינים על ידי התקשרות isExternalOfferAvailableAsync

ה-API הזה מחזיר BillingResponseCode.OK אם יש מבצעים חיצוניים. במאמר טיפול בתגובות מוסבר איך האפליקציה צריכה לפעול להגיב לקודי תגובה אחרים.

Kotlin


billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers unavailable, etc.
            return
        }

        // External offers are available. Continue with steps in the
        // guide.
})

Java


billingClient.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external offers being unavailable, etc.
            return;
        }
        // External offers are available. Continue with steps in the
        // guide.
      }

});

הכנה של אסימון עסקה חיצוני

כדי לדווח על עסקה חיצונית ל-Google Play, צריך משתמש חיצוני אסימון עסקה שנוצר מספריית החיובים ב-Play. משתמש חיצוני חדש יש ליצור אסימון עסקה בכל פעם שהמשתמש מבקר באתר אתר באמצעות ה-API של המבצעים החיצוניים. כדי לעשות זאת, שולחים createExternalOfferReportingDetailsAsync API. האסימון הזה צריך להיות שנוצרת מיד לפני שהמשתמש מופנה אל מחוץ לאפליקציה. היא צריכה אף פעם לא יישמרו במטמון ויש ליצור נכס חדש בכל פעם שהמשתמש מופנה מחוץ לאפליקציה.

Kotlin


billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

Java


billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

תיבת דו-שיח עם מידע למשתמשים

כדי לשלב מבצעים חיצוניים, האפליקציה שעומדת בדרישות צריכה להציג מידע שעוזר למשתמשים להבין שהם עומדים להיות מועברים אל מחוץ מהאפליקציה לאתר חיצוני. חובה להציג את מסך המידע למשתמשים עד לשלוח קריאה ל-API showExternalOfferInformationDialog לפני שמקשרים ל במבצע חיצוני בכל פעם.

Kotlin


// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

Java


// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

אם השיטה הזו מחזירה BillingResponseCode.OK, האפליקציה יכולה להמשיך אל להפנות את המשתמשים לאתר החיצוני. אם השיטה מחזירה BillingResponseCode.USER_CANCELED, אסור לאפליקציה להמשיך לפתוח את ה האתר.

דיווח על עסקאות ל-Google Play

יש לדווח ל-Google Play על כל העסקאות החיצוניות באמצעות קריאה ל-Google Play Developer API מהקצה העורפי שלך. עסקאות חיצוניות חייבות לדווח externalTransactionToken הושג באמצעות API של createExternalOfferReportingDetailsAsync. אם משתמש מבצע כמה פעמים רכישות, אפשר להשתמש externalTransactionToken כדי לדווח על כל רכישה. כדי ללמוד איך לדווח על לעסקה הזו, ראו מדריך לשילוב קצה עורפי.

טיפול בתשובה

כשמתרחשת שגיאה, השיטות isExternalOfferAvailableAsync, createExternalOfferReportingDetailsAsync, וגם showExternalOfferInformationDialog עשוי להחזיר תשובות שאינן BillingResponseCode.OK מומלץ לטפל בקודי התגובה האלה באופן הבא:

  • ERROR: זוהי שגיאה פנימית. לא להמשיך בביצוע העסקה או לפתוח את האתר החיצוני. רוצה לנסות שוב? showExternalOfferInformationDialog() כדי להציג את המידע למשתמש בפעם הבאה שתנסו להפנות אותו אל מחוץ אפליקציה.
  • FEATURE_NOT_SUPPORTED: ממשקי ה-API של המבצעים החיצוניים לא נתמכים על ידי חנות Play במכשיר הנוכחי. לא להמשיך בביצוע העסקה או לפתוח את האתר החיצוני.
  • USER_CANCELED: לא להמשיך בפתיחת האתר החיצוני. שיחת טלפון צריך ללחוץ שוב על showExternalOfferInformationDialog() כדי להציג את המידע למשתמש בפעם הבאה שתנסו להפנות אותו אל מחוץ אל את האפליקציה.
  • BILLING_UNAVAILABLE: העסקה לא עומדת בדרישות למבצעים חיצוניים ולכן היא לא יכולה להמשיך במסגרת התוכנית הזו. זה יכול לקרות מהסיבות הבאות אם המשתמש לא נמצא במדינה שבה אפשר להשתתף בתוכנית הזו, או שהחשבון שלך לא נרשם בהצלחה לתוכנית. אם הכירו את האפשרות השנייה, בדקו סטטוס הרישום שלך ב-Play Developer Console.
  • DEVELOPER_ERROR: יש שגיאה בבקשה. שימוש בהודעה על תוצאות ניפוי הבאגים כדי לזהות ולתקן את השגיאה לפני שממשיכים.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: אלה שגיאות זמניות שצריך לטפל בהן באמצעות מדיניות מתאימה בנושא ניסיונות חוזרים. במקרה של SERVICE_DISCONNECTED, צריך ליצור מחדש את החיבור עם Google Play לפני הניסיון הבא.

בדיקה של מבצעים חיצוניים

צריך להשתמש בבודקי הרישיונות כדי לבדוק את השילוב של המבצעים החיצוניים. שלך לא יחויבו עבור עסקאות שבוצעו על ידי בודקי הרישיון. חשבונות. מידע נוסף זמין במאמר בדיקה של החיוב על רכישות באפליקציות באמצעות רישוי אפליקציה על הגדרה של בודקי רישיונות.

השלבים הבאים

כשתסיימו לשלב באפליקציה, אתם מוכנים לשלב הקצה העורפי.