מעבר לספריית החיובים של Google Play מגרסה 6 מגרסאות 4 או 5

במאמר הזה מוסבר איך לעבור מספריית החיובים ב-Google Play בגרסה 4 או 5 לספריית החיובים ב-Google Play בגרסה 6, ואיך להשתמש ביכולות החדשות של המינויים.

הרשימה המלאה של השינויים בגרסה 6.0.0 מפורטת בנתוני הגרסה.

סקירה כללית

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

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

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

כל המוצרים הקיימים מסוג מינוי הומרו באופן אוטומטי למודל החדש הזה, כחלק מהגרסה של ספריית החיובים ב-Play 5 ופלטפורמת המינויים החדשה שהושקו במאי 2022. כלומר, אתם לא צריכים לשנות את ההגדרות של מוצרים מסוג מינוי כדי שהקטלוג יהיה תואם לגרסאות החדשות של ספריית החיובים ב-Play. למידע נוסף על האופן שבו מק"טים של מינויים הומרו למינויים שתואמים לדורות קודמים, עיינו בקטע עבודה עם מינויים ישנים יותר במאמר העזרה של Play Console.

גרסאות קודמות של האפליקציה עדיין פועלות

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

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

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

גרסאות 5 ו-6 של ספריית החיובים ב-Play כוללות את השיטות שהוצאו משימוש querySkuDetailsAsync ו-BillingFlowParams.Builder.setSkuDetails, שמקבלות את SkuDetails כפרמטר של רצף פעולות החיוב. זה אומר שאתם יכולים לעבור בהדרגה לספריית החיובים ב-Play בגרסה 6, על ידי תכנון של שלבי המיגרציה השונים.

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

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

שלבים להעברה מלאה

יצירת מינויים חדשים בקטלוג המוצרים שלכם בקצה העורפי

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

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

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

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

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

  • ב-backend, אם תערכו את המינויים שהומרו בממשק המשתמש של Play Console, לא תוכלו לנהל אותם באמצעות נקודת הקצה inappproducts, אם קראתם לנקודת הקצה למטרה הזו. כדי לנהל את הרכישות של המינויים האלה, צריך גם לעבור לנקודת הקצה החדשה של סטטוס הרכישה של המינוי (purchases.subscriptionsv2.get), כי נקודת הקצה הישנה של סטטוס הרכישה (purchases.subscriptions.get) מחזירה רק את הנתונים שנדרשים כדי לטפל ברכישות של מינויים בסיסיים ומבצעים שתואמים לדורות קודמים. למידע נוסף, קראו את הקטע ניהול סטטוס הרכישה של מינוי.

ניהול קטלוג המינויים בקצה העורפי באמצעות ה-API החדש

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

כדי להעביר מודול אוטומטי לניהול קטלוג מוצרים למינויים בחיוב דרך Google Play, צריך להחליף את ה-API של inappproducts ב-Subscription Publishing API החדש כדי לנהל ולפרסם את קטלוג המינויים. יש שלוש נקודות קצה חדשות:

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

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

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

עדכון ספריית החיובים ב-Google Play

אחרי שתיצרו את קטלוג המוצרים החדש מסוג מינוי, תוכלו להעביר את האפליקציה לגרסה 5 של ספריית החיובים ב-Google Play. מחליפים את יחסי התלות הקיימים של ספריית החיובים ב-Play בגרסה המעודכנת בקובץ build.gradle של האפליקציה.

dependencies {
    def billingVersion = "6.0.0"

    implementation "com.android.billingclient:billing:$billingVersion"
}

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

מאתחלים את לקוח החיוב ויוצרים חיבור ל-Google Play

השלבים הראשונים להפעלת רכישות מאפליקציה ל-Android נשארים זהים:

הצגת מוצרים שזמינים לקנייה

כדי לקבל את כל המבצעים שהמשתמש זכאי לרכוש:

  • מחליפים את SkuDetailsParams ב-QueryProductDetailsParams
  • העברת השיחה ב-BillingClient.querySkuDetailsAsync() לשימוש ב-BillingClient.queryProductDetailsAsync()

שימו לב שתוצאות השאילתה הן עכשיו ProductDetails במקום SkuDetails. כל פריט ProductDetails מכיל את המידע על המוצר (מזהה, שם, סוג וכו'). במוצרים מסוג מינוי, ProductDetails מכיל List<ProductDetails.SubscriptionOfferDetails>, שהוא רשימת הפרטים של מבצע המינוי. במוצרים לרכישה חד-פעמית, ProductDetails מכיל ProductDetails.OneTimePurchaseOfferDetails. אפשר להשתמש בהם כדי להחליט אילו מבצעים להציג למשתמשים.

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

לפני

Kotlin

val skuList = ArrayList<String>()

skuList.add("up_basic_sub")

val params = SkuDetailsParams.newBuilder()

params.setSkusList(skuList).setType(BillingClient.SkuType.SUBS).build()

billingClient.querySkuDetailsAsync(params) {
    billingResult,
    skuDetailsList ->
    // Process the result
}

Java

List<String> skuList = new ArrayList<>();

skuList.add("up_basic_sub");

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();

params.setSkusList(skuList).setType(SkuType.SUBS).build();

billingClient.querySkuDetailsAsync(params,
    new SkuDetailsResponseListener() {
        @Override
        public void onSkuDetailsResponse(BillingResult billingResult,
                List<SkuDetails> skuDetailsList) {
            // Process the result.
        }
    }
);

אחרי

Kotlin

val productList =
    listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("up_basic_sub")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )

val params = QueryProductDetailsParams.newBuilder().setProductList(productList).build()

billingClient.queryProductDetailsAsync(params) {
    billingResult,
    productDetailsList ->
    // Process the result
}

Java

ImmutableList<Product> productList = ImmutableList.of(Product.newBuilder()
                                            .setProductId("up_basic_sub")
                                            .setProductType(ProductType.SUBS)
                                            .build());

QueryProductDetailsParams params = QueryProductDetailsParams.newBuilder()
    .setProductList(productList)
    .build();

billingClient.queryProductDetailsAsync(
        params,
        new ProductDetailsResponseListener() {
                public void onProductDetailsResponse(BillingResult billingResult, List<ProductDetails> productDetailsList) {
                    // Process the result
                }
        }
);

הקריאה החוזרת (callback) של queryProductDetailsAsync מחזירה List<ProductDetails>. כל פריט ProductDetails מכיל את המידע על המוצר (מזהה, שם, סוג וכו'). ההבדל העיקרי הוא שמוצרים מסוג מינוי מכילים עכשיו גם List<ProductDetails.SubscriptionOfferDetails> שכולל את כל המבצעים שזמינים למשתמש.

בגרסאות קודמות של ספריית החיובים ב-Play אין תמיכה באובייקטים החדשים (מינויים, מינויים בסיסיים, מבצעים וכו'), ולכן המערכת החדשה מתרגמת כל מק"ט של מינוי למינוי בסיסי ולמבצע יחידים שתואמים לדורות קודמים. מוצרים זמינים לרכישה חד-פעמית מועברים גם לאובייקט ProductDetails. אפשר לגשת לפרטי המבצע של מוצר ברכישה חד-פעמית באמצעות השיטה getOneTimePurchaseOfferDetails().

במקרים נדירים, מכשירים מסוימים לא תומכים ב-ProductDetails וב-queryProductDetailsAsync(), בדרך כלל בגלל גרסאות מיושנות של Google Play Services. כדי לוודא שהתרחיש הזה נתמך כמו שצריך, צריך להפעיל את isFeatureSupported() לתכונה PRODUCT_DETAILS לפני שמפעילים את queryProductDetailsAsync. אם התגובה היא OK, המכשיר תומך בתכונה ואפשר להמשיך לקריאה ל-queryProductDetailsAsync(). אם התגובה היא FEATURE_NOT_SUPPORTED, אתם יכולים לבקש את רשימת המוצרים הזמינים שתואמים לדורות קודמים באמצעות querySkuDetailsAsync(). מידע נוסף על השימוש בתכונות התאימות לדורות קודמים זמין במדריך לתכונות המינויים ממאי 2022.

הפעלת תהליך הרכישה של המבצע

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

  • במקום להשתמש ב-SkuDetails בשביל BillingFlowParams, צריך להשתמש ב-ProductDetailsParams.
  • אפשר לקבל את פרטי המבצע, כמו מזהה המבצע, מזהה המינוי הבסיסי ועוד, באמצעות האובייקט SubscriptionOfferDetails.

כדי לרכוש מוצר עם המבצע שהמשתמש בחר, צריך לקבל את ה-offerToken של המבצע שנבחר ולהעביר אותו לאובייקט ProductDetailsParams.

אחרי שיוצרים אובייקט BillingFlowParams, הפעלת רצף פעולות החיוב באמצעות BillingClient נשארת ללא שינוי.

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

לפני

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
val billingFlowParams = BillingFlowParams.newBuilder()
                            .setSkuDetails(skuDetails)
                            .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;
// Retrieve a value for "skuDetails" by calling querySkuDetailsAsync().
BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
        .setSkuDetails(skuDetails)
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

אחרי

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time product, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get the offer token corresponding to the selected
        // offer call productDetails.subscriptionOfferDetails?.get(selectedOfferIndex)?.offerToken
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get the offer token corresponding to the selected
            // offer call productDetails.getSubscriptionOfferDetails().get(selectedOfferIndex).getOfferToken()
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

לעבד את הרכישות

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

כדי לשלוף את כל הרכישות הפעילות שבבעלות המשתמש ולשאול לגבי רכישות חדשות:

  • במקום להעביר ערך BillingClient.SkuType אל queryPurchasesAsync(), מעבירים אובייקט QueryPurchasesParams שמכיל ערך BillingClient.ProductType.

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

לפני

Kotlin

billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) {
    billingResult,
    purchaseList -> {
        // Process the result
    }
}

Java

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // process the result
        }
    }
);

אחרי

Kotlin

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder()
        .setProductType(BillingClient.ProductType.SUBS)
        .build()
) { billingResult, purchaseList ->
    // Process the result
}

Java

billingClient.queryPurchasesAsync(
    QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(),
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                List<Purchase> purchases) {
            // Process the result
        }
    }
);

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

ניהול סטטוס הרכישה של המינוי באמצעות ה-API החדש בקצה העורפי

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

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

כשמעבירים את מודול ניהול סטטוס הרכישה:

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

שינוי רכישות של מינויים של משתמשים

בגרסה 5 של ספריית החיובים ב-Play ובגרסאות קודמות, השתמשו ב-ProrationMode כדי להחיל שינויים על רכישות של מינויים של משתמשים, כמו שדרוגים או שדרוגים לאחור. השדה הזה הוצא משימוש והוחלף בשדה ReplacementMode בגרסה 6.

טיפול בשינויים במחירי המינויים

ה-API ‏launchPriceConfirmationFlow שהוצא משימוש בעבר הוסר מספריית החיובים ב-Play בגרסה 6. למידע על חלופות, אפשר לעיין במדריך לשינויים במחירים.

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

בספריית החיובים ב-Play בגרסה 6, נוסף קוד NETWORK_ERROR חדש שמציין בעיות בחיבור לרשת בין המכשיר של המשתמש לבין מערכת Google Play. היו גם שינויים בקודים SERVICE_TIMEOUT ו-SERVICE_UNAVAILABLE. מידע נוסף זמין במאמר טיפול בקודי תגובה של BillingResult.

טיפול בעסקאות בהמתנה

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