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

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

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

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

חיבור ל-Google Play

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

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

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

Kotlin

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

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

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

Java

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, בלי אפשרות בחירה למשתמש.

המדינה ב-Play של המשתמש היא מדינה נתמכת

המדינה של המשתמש ב-Play לא נתמכת

הפונקציה enableUserChoiceBilling נקראת במהלך ההגדרה של BillingClient

המשתמש רואה את ממשק המשתמש של בחירת המשתמש

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

הפונקציה enableUserChoiceBilling לא מופעלת במהלך ההגדרה של BillingClient

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

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

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

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

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

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

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

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

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

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

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

Kotlin

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.
    }

Java

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() במקרה הזה יוצרת אסימון חדש של עסקה חיצונית לעסקה, שאפשר לאחזר מהקריאה החוזרת.

Kotlin

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

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

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

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

Java

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

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using 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 של המבצע שנבחר לתוכנית החדשה:

    Kotlin

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

    Java

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

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

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

    BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
            )
        )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.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() תופעל במקרה הזה, כמו שמתואר במאמר הפעלת תהליך החיוב לבחירת המשתמש.

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

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

השלבים הבאים

אחרי שתסיימו את השילוב באפליקציה, תוכלו לשלב את ה-Backend.