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

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

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

סקירה כללית

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Monetization.subscriptions לניהול מוצרים במינוי.
• Monetization.basePlans כדי לנהל מינויים בסיסיים למינויים.
• Monetization.offers כדי לנהל מבצעים למינויים בסיסיים.

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

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

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

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

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

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

dependencies {
    def billingVersion = "6.0.0"

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

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

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

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

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

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

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

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

• מחליפים את 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
                }
        }
);

הקריאה החוזרת של 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.

הערה: אם אתם עוברים מגרסה 4, שימו לב שהגרסאות הקודמות שהוצאו משימוש השיטה queryPurchases הוסרה בספריית החיובים ב-Play 6. כדאי להשתמש queryPurchasesAsync במקום זאת, כפי שמוצג בהמשך.

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

לפני

Kotlin

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

Java

billingClient.queryPurchasesAsync(
    BillingClient.SkuType.SUBS,
    new PurchasesResponseListener() {
        public void onQueryPurchasesResponse(
                BillingResult billingResult,
                ListP<urchase >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 בקצה העורפי. בגרסה הישנה של ה-API לא מוצגים כל הפרטים הנדרשים לניהול רכישות בפלטפורמה החדשה. לקבלת פרטים על שינויים מגרסאות קודמות: כדאי לעיין במדריך לתכונות המינויים החדשות במאי 2022.

בדרך כלל קוראים ל-Subscription Purchases API בכל פעם שמקבלים SubscriptionNotification הודעה בזמן אמת למפתחים כדי למשוך את מידע עדכני על סטטוס המינוי. צריך להחליף את שיחות אל purchases.subscriptions.get עם הגרסה החדשה של Subscription Purchases API, purchases.subscriptionsv2.get. יש משאב חדש בשם SubscriptionPurchaseV2 שמספק מספיק מידע לניהול הרשאה לרכישה למינויים במודל החדש.

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

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

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

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

ה-API של launchPriceConfirmationFlow שהוצא משימוש בעבר הוסר ב- ספריית החיובים ב-Play 6. למידע נוסף, אפשר לעיין בקטע שינויים במחירים guide.

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

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

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

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