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

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

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

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

חיבור ל-Google Play

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

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

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

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

הצגת המוצרים הזמינים

אפשר להציג מוצרים זמינים למשתמש באותו אופן כמו: שילוב של מערכת החיוב של Google Play. מתי המשתמש ראה את המוצרים זמין לרכישה ובוחרת פריט לקנייה, מפעילים את האפשרות 'חיוב לבחירת המשתמש' בתהליך ההגדרה, כפי שמתואר בקטע הבא.

הפעלת תהליך החיוב לבחירת המשתמש

כדי להפעיל את תהליך החיוב לבחירת המשתמש, צריך להפעיל את launchBillingFlow(). זה עובד כמו השקה של תהליך רכישה באמצעות מערכת חיוב של Google Play שילוב: מספקים מכונת ProductDetails ו-offerToken שמתאימות למוצר ולהצעה שהמשתמש רוצה לרכוש. אם המיקום המשתמש בוחר את מערכת החיוב של Google Play, המידע הזה משמש להמשיך בתהליך הרכישה.

כשמפתחים מתקשרים למספר launchBillingFlow(), מערכת החיוב של Google Play מבצע את הבדיקה הבאה:

• המערכת בודקת אם המדינה ב-Google Play של המשתמש היא מדינה שתומכת במערכת חיוב חלופית באמצעות בחירת המשתמש (כלומר מדינה). אם יש תמיכה במדינה של המשתמש ב-Google Play, מערכת Google Play בודקת האם מערכת חיוב חלופית הופעלה על סמך ההגדרות של BillingClient.
  • אם הופעלה מערכת חיוב חלופית עם אפשרות הבחירה של המשתמש, הרכישה מציג את חוויית המשתמש של בחירת המשתמש.
  • אם מערכת חיוב חלופית עם בחירת המשתמש לא מופעלת, הרכישה מציג את חוויית המשתמש הרגילה במערכת החיוב של Google Play, ללא משתמש בחירה.
• אם המדינה של המשתמש ב-Google Play היא לא מדינה נתמכת, תהליך הרכישה מציג את חוויית המשתמש הרגילה במערכת החיוב של Google Play, ללא המשתמש בחירה.

טיפול בבחירת המשתמש

האופן שבו תטפלו בשאר השלבים של תהליך הרכישה תלוי בגורמים הבאים: המשתמש בחר במערכת החיוב של Google Play או במערכת חיוב חלופית.

כשהמשתמש בוחר מערכת חיוב חלופית

אם המשתמש בוחר במערכת החיוב החלופית, מתבצעת קריאה מ-Google Play אל UserChoiceBillingListener כדי להודיע לאפליקציה שהיא צריכה להפעיל את תהליך הרכישה במערכת חיוב חלופית. באופן ספציפי, בוצעה קריאה לשיטה userSelectedAlternativeBilling().

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

ה-UserChoiceBillingListener צריך לבצע את הפעולות הבאות:

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

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

הדוגמה הבאה ממחישה איך להטמיע את התג UserChoiceBillingListener:

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

כשהמשתמש בוחר במערכת החיוב של Google Play

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

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

טיפול בשינויים במינוי

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

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

תהליכי השדרוג והשדרוג לאחור

שינויים בתוכנית המנויים, כולל תהליכי השדרוג והשדרוג לאחור, צריכים להיות אופן הטיפול שונה בהתאם לאופן שבו המינוי נקנה במקור באמצעות מערכת החיוב של Google Play או דרך מערכת חיוב חלופית.

תוספים שתלויים במינוי קיים שמוגדר להם אותו אמצעי תשלום, והתאמה של חיובים קבועים מטופלים כשדרוגים. לגבי תוספים אחרים, משתמשים הם יוכלו לבחור באיזו מערכת חיוב הם רוצים להשתמש. הפעלה של חוויית הרכישה באמצעות launchBillingFlow(), כפי שמתואר במאמר הפעלת תהליך החיוב לבחירת המשתמש.

מינויים שנקנו דרך מערכת חיוב חלופית

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

כדי לעשות זאת, צריך להתקשר אל launchBillingFlow() כשהמשתמש מבקש שדרוג או לשדרג לאחור. במקום לציין אובייקט SubscriptionUpdateParams בקוד משתמשים ב-setOriginalExternalTransactionId, כדי לציין של הרכישה המקורית. הפעולה הזו לא מציגה את המשתמש מסך הבחירה, מכיוון שבחירת המשתמש ברכישה המקורית נשמרת לשדרוגים ולשדרוגים לאחור. הקריאה אל launchBillingFlow() במקרה הזה יוצר אסימון עסקה חיצוני חדש לעסקה שאפשר אחזור מהקריאה החוזרת.

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched via queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync.
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails
                        .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    .setOriginalExternalTransactionId(externalTransactionId)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

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

מינויים שנקנו דרך מערכת החיוב של Google Play

באופן דומה, משתמשים שקנו את המינוי הנוכחי שלהם דרך Google Play את מערכת החיוב אחרי בחירת המשתמש צריך להציג את תהליך השדרוג או השדרוג לאחור. במערכת החיוב של Google Play. בהוראות הבאות מתואר איך צריך להפעיל את תהליך הרכישה של שדרוג או שדרוג לאחור דרך Google. מערכת החיוב של Play:

1. צריך לזהות את offerToken של המבצע שנבחר בתוכנית החדשה:

val offerTokenNewPlan = productDetailsNewPlan
             .getSubscriptionOfferDetails(selectedOfferIndex)
             .getOfferToken()

String offerTokenNewPlan = productDetailsNewPlan
                     .getSubscriptionOfferDetails(selectedOfferIndex)
                     .getOfferToken();

1. יש לשלוח את המידע הנכון אל מערכת החיוב של Google Play לצורך עיבוד רכישה חדשה, כולל אסימון הרכישה של המינוי הקיים:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via queryProductDetailsAsync
                        .setProductDetails(productDetailsNewPlan)
                        // offerIdToken can be found in
                        // ProductDetails=>SubscriptionOfferDetails.
                        .setOfferToken(offerTokenNewPlan)
                        .build()
                )
            )
            .setSubscriptionUpdateParams(
                SubscriptionUpdateParams.newBuilder()
                    // purchaseToken can be found in
                    // Purchase#getPurchaseToken
                    .setOldPurchaseToken("old_purchase_token")
                    .setReplaceProrationMode(ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                    .build()
            )
            .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

הרכישה הזו מתבצעת במערכת החיוב של Google Play והאפליקציה שלך מקבלת את הקריאה PurchasesUpdatedListener.onPurchaseUpdated עם תוצאת רכישה. אם הרכישה בוצעה בהצלחה, גם השיטה onPurchaseUpdated() מקבל את פרטי הרכישה החדשים, והקצה העורפי שלכם מקבל SUBSCRIPTION_PURCHASED הודעה בזמן אמת למפתחים. כשמושכים את הרכיב סטטוס של הרכישה החדשה, מאפיין linkedPurchaseToken מקשר של רכישת מינוי כדי שתוכל להוציא אותו משימוש בתור מומלץ.

ביטול ושחזור של מינויים

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

במקרים רבים המשתמשים מחליטים לבטל את הביטול של תקופת הפעילות. במדריך הזה, הפעולה הזו נקראת שחזור. הבאים בקטעים הבאים מתואר איך לטפל בתרחישי שחזור של ממשק ה-API לחיוב.

מינויים שנקנו דרך מערכת חיוב חלופית

אם יש לכם מזהה עסקה חיצוני למינוי שבוטל, הוא לא צריך להתקשר אל launchBillingFlow() כדי לשחזר את המינוי, לכן לא אמור לשמש להפעלה מהסוג הזה. אם משתמש משחזר את בזמן המינוי שבוטל, לא העסקה מתרחשת באותו זמן; אפשר פשוט להמשיך לדווח על החידוש כאשר המחזור הנוכחי יסתיים והחידוש הבא יתבצע. הדבר כולל מקרים שבהם המשתמש מקבל זיכוי או מחיר חידוש מיוחד כחלק מהשחזור (לדוגמה, מבצע שמעודד את המשתמש להמשיך במינוי).

מינויים שנקנו דרך מערכת החיוב של Google Play

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

אפשר גם להפעיל שחזור במערכת החיוב של Google Play מהאפליקציה באמצעות התקשרות אל launchBillingFlow(). לעיון בקטע לפני פקיעת התוקף של המינוי - באפליקציה כדי להסביר איך לעשות זאת. עבור משתמשים שעברו בתהליך בחירת המשתמש עבור הרכישה המקורית (שבוטלה אבל עדיין פעיל), המערכת מזהה באופן אוטומטי את הבחירה שלו ומציגה את ממשק המשתמש לשחזור הרכישות האלה. הם מתבקשים לאשר את לרכוש את המינוי מחדש דרך Google Play, אבל לא צריך להעביר אותו בתהליך הבחירה של המשתמש. אסימון רכישה חדש הונפק עבור המשתמש במקרה הזה. הקצה העורפי מקבל SUBSCRIPTION_PURCHASED בזמן אמת הודעה למפתחים, והערך linkedPurchaseToken של הרכישה החדשה הסטטוס מוגדר כמו במקרה של שדרוג או שדרוג לאחור, עם הרכישה הישנה האסימון של המינוי שבוטל.

מינויים מחדש

אם תוקף המינוי פג במלואו, בין אם בעקבות ביטולו או תשלום שנדחה ללא שחזור (השהיית חשבון שפג תוקפה), על המשתמש להירשם מחדש אם רוצים להפעיל מחדש את ההרשאה.

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

בדיקה של מערכת החיוב החלופית

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

השלבים הבאים

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