این مبحث نحوه انتقال از کتابخانه صورتحساب Google Play 4 یا 5 به Google Play Billing Library 6 و نحوه استفاده از قابلیتهای اشتراک جدید را شرح میدهد.
برای لیست کامل تغییرات در نسخه 6.0.0، به یادداشت های انتشار مراجعه کنید.
نمای کلی
Google Play Billing Library 6 بر اساس ویژگیهای اشتراک جدید معرفیشده در نسخه 5 ساخته شده است و چند پیشرفت دیگر اضافه میکند. این ویژگیها به شما امکان میدهد اشتراکها را به روشهای بیشتری بفروشید و با حذف نیاز به ایجاد و مدیریت تعداد فزاینده SKU، هزینههای عملیاتی را کاهش دهید.
برای اطلاعات بیشتر درباره ویژگیهای جدید معرفیشده با Play Billing Library 5، به تغییرات اخیر در اشتراکها در Play Console مراجعه کنید.
ارتقای کتابخانه صورتحساب Play سازگار با عقب
همه محصولات اشتراک موجود بهعنوان بخشی از نسخه مه 2022 Play Billing Library 5 و پلتفرم اشتراکهای جدید، بهطور خودکار به این پارادایم جدید تبدیل شدند. این بدان معناست که برای داشتن کاتالوگی سازگار با نسخههای جدید کتابخانه صورتحساب Play، نیازی به تغییر در پیکربندی محصول اشتراک ندارید. برای اطلاعات بیشتر در مورد نحوه تبدیل SKUهای اشتراک به اشتراکهای سازگار با عقب، به بخش کار با اشتراکهای قدیمی در مقاله راهنمای کنسول Play مراجعه کنید.
نسخههای قدیمیتر برنامه شما همچنان کار میکنند
اگر یک کاتالوگ اشتراک سازگار با نسخه قبلی دارید، همه نسخه های موجود برنامه شما همچنان باید همانطور که برای آن محصولات در نظر گرفته شده است کار کنند. خرید یکبار محصول نیز باید بدون مشکل در نسخههای قدیمیتر کار کند.
نسخههای برنامه شما که از روشهای منسوخ شده استفاده میکنند (مثلا querySkuDetailsAsync()
) نمیتوانند هیچ طرح یا پیشنهادی پایه را بفروشند که با نسخه قبلی سازگار نیست. میتوانید در مقاله مرکز راهنمای کنسول Play مربوطه، درباره پیشنهادات سازگار با نسخه قبلی بخوانید.
به Play Billing Library 5 یا 6 ارتقا دهید
Play Billing Library 5 و 6 شامل روشهای منسوخ querySkuDetailsAsync
و BillingFlowParams.Builder.setSkuDetails
است که SkuDetails
به عنوان پارامتر جریان صورتحساب میگیرد. این بدان معناست که با برنامه ریزی مراحل مختلف مهاجرت می توانید به تدریج به Play Billing Library 6 بروید.
به عنوان اولین گام برای انتقال، میتوانید نسخه کتابخانه را بهروزرسانی کنید ، کاتالوگ و باطن خود را همانطور که هستند رها کنید و برنامه خود را در حالی که هنوز از روشهای منسوخ شده استفاده میکند آزمایش کنید. اگر از queryPurchases
، launchPriceChangeFlow
، یا setVrPurchaseFlow
استفاده نمیکنید، همچنان باید طبق برنامه کار کند. پس از آن، می توانید تکرار کنید تا به طور کامل ویژگی های اشتراک جدید منتشر شده در می 2022 را بپذیرید.
اگر قبلاً از این ویژگیها با انتقال Google Play Billing Library 5 استفاده کردهاید، میتوانید مستقیماً به بخشهایی با عنوان بهروزرسانی کتابخانه صورتحساب Google Play و تغییر خریدهای اشتراک کاربر بروید. اگر از نسخه قبلی شروع میکنید یا هنوز ویژگیهای جدید را به طور کامل به کار نبردهاید، میتوانید مراحل انتقال کامل را که در ادامه میآید را بخوانید تا نحوه استفاده از آنها را بیاموزید.
مراحل مهاجرت کامل
اشتراک های جدید در کاتالوگ محصولات باطن خود ایجاد کنید
با استفاده از Play Developer Console یا Play Developer API، اکنون می توانید یک اشتراک را با چندین طرح پایه، که هر کدام دارای چندین پیشنهاد است، پیکربندی کنید. پیشنهادات اشتراک دارای مدلهای قیمتگذاری انعطافپذیر و گزینههای واجد شرایط بودن هستند. میتوانید با استفاده از انواع طرحهای تمدید خودکار و پیشپرداخت پیشنهادات را در طول چرخه عمر اشتراک ایجاد کنید.
توصیه میکنیم قبل از انتقال برنامه، محصولات جدیدی را به دنبال ساختار موجودیت در پلتفرم اشتراک جدید برای ادغام Play Billing Library 6 خود ایجاد کنید. میتوانید محصولات تکراری را در کاتالوگ قدیمیتان که نشاندهنده همان مزایای استحقاق است، تحت یک اشتراک واحد تجمیع کنید و از طرح پایه استفاده کنید و پیکربندیهایی را برای نمایش همه گزینههایی که میخواهید ارائه دهید، ارائه دهید. برای اطلاعات بیشتر درباره این توصیه، به بخش کار با اشتراکهای قدیمیتر در مقاله راهنمای کنسول Play مراجعه کنید.
توصیه می کنیم محصولات اشتراک تبدیل شده را پس از انتشار می 2022 تغییر ندهید. باید آنها را همانطور که قرار است با نسخههای برنامه شما با استفاده از روشهای منسوخ فروخته شوند (به عنوان مثال querySkuDetailsAsync()
) بدون ایجاد تغییراتی که میتواند بر این ساختهای قدیمیتر تأثیر بگذارد، رها کنید.
فرآیند تبدیل، محصولات اشتراکی را که قبل از ماه مه 2022 در کاتالوگ شما بودند، فقط خواندنی کرد تا از تغییرات تصادفی که میتواند منجر به مشکلاتی در ادغام فعلی شما شود، جلوگیری شود. ایجاد تغییرات در این اشتراکها امکانپذیر است، اما پیامدهایی وجود دارد که میتواند بر ادغام ظاهر و باطن شما تأثیر بگذارد:
در ظاهر، نسخههای برنامه با استفاده از
querySkuDetailsAsync()
برای به دست آوردن جزئیات محصول اشتراک، فقط میتوانند طرحها و پیشنهادات پایه سازگار با عقب را بفروشند، و تنها میتواند یک طرح پایه و ترکیب پیشنهادی سازگار با عقب را بفروشد، بنابراین اگر طرحها یا پیشنهادات جدیدی به آن اضافه کنید. اشتراکهای تبدیلشده، طرحها یا پیشنهادات پایه اضافی جدید نمیتوانند در این نسخههای قدیمیتر برنامه شما فروخته شوند.در باطن، اگر اشتراکهای تبدیلشده خود را در رابط کاربری کنسول Play ویرایش کنید، نمیتوانید آنها را با نقطه پایانی
inappproducts
مدیریت کنید، اگر برای این منظور با نقطه پایانی تماس میگیرید. همچنین باید برای مدیریت خریدهای این اشتراکها به نقطه پایانی وضعیت خرید اشتراک جدید (purchases.subscriptionsv2.get
) مهاجرت کنید، زیرا نقطه پایانی وضعیت خرید قدیمی (purchases.subscriptions.get
) فقط دادههای لازم برای مدیریت طرحهای پایه سازگار با عقب را برمیگرداند. و خرید ارائه می دهد. برای اطلاعات بیشتر بخش مدیریت وضعیت خرید اشتراک را بخوانید.
کاتالوگ اشتراک باطن خود را با API جدید مدیریت کنید
اگر کاتالوگ محصولات اشتراک خود را بهطور خودکار با Google Play Developer API مدیریت میکنید، باید از نقاط پایانی تعریف محصول اشتراک جدید برای ایجاد و مدیریت اشتراکها، طرحهای پایه و پیشنهادات استفاده کنید. راهنمای ویژگیهای اشتراک می 2022 را بخوانید تا درباره تغییرات API کاتالوگ محصول برای این نسخه بیشتر بدانید.
برای انتقال یک ماژول مدیریت خودکار کاتالوگ محصول برای اشتراکهای صورتحساب Google Play، API inappproducts
را با API انتشار اشتراک جدید جایگزین کنید تا کاتالوگ اشتراک خود را مدیریت و منتشر کنید. سه نقطه پایانی جدید وجود دارد:
-
Monetization.subscriptions
برای مدیریت محصولات اشتراک. -
Monetization.basePlans
برای مدیریت برنامه های پایه برای اشتراک ها. -
Monetization.offers
برای مدیریت پیشنهادات برای طرح های پایه.
این نقاط پایانی جدید همه عملکردهای لازم را برای استفاده از همه قابلیتهای جدید در کاتالوگ شما دارند: برچسبهای طرح پایه و پیشنهاد، هدفگیری منطقهای، طرحهای پیشپرداخت و موارد دیگر.
همچنان باید از inappproducts
API برای مدیریت کاتالوگ محصولات درون برنامهای خود برای محصولات یکبار خرید استفاده کنید.
نسخههای برنامه شما که از روشهای منسوخ شده استفاده میکنند (مثلا querySkuDetailsAsync()
) نمیتوانند هیچ طرح یا پیشنهادی پایه را بفروشند که با نسخه قبلی سازگار نیست. میتوانید در اینجا درباره پیشنهادهای سازگار با عقبنما بخوانید.
کتابخانه صورتحساب Google Play را بهروزرسانی کنید
پس از ایجاد کاتالوگ محصولات اشتراک جدید خود، می توانید برنامه خود را به کتابخانه صورتحساب Google 5 منتقل کنید. وابستگی موجود کتابخانه صورتحساب Play را با نسخه به روز شده در فایل build.gradle
برنامه خود جایگزین کنید.
dependencies {
def billingVersion = "6.0.0"
implementation "com.android.billingclient:billing:$billingVersion"
}
پروژه شما باید فوراً ساخته شود، حتی اگر هیچ تماسی را به روشها تغییر نداده باشید—Play Billing Library 6 با نسخه قبلی سازگار است. مفهوم SKU منسوخ تلقی می شود، اما همچنان وجود دارد تا انتقال برنامه ها به فرآیندی ساده تر و تدریجی تر تبدیل شود.
Billing Client را راه اندازی کنید و با Google Play ارتباط برقرار کنید
اولین گامها برای راهاندازی خرید از یک برنامه Android یکسان است:
نمایش محصولات موجود برای خرید
برای دریافت همه پیشنهادات، کاربر واجد شرایط خرید است:
-
SkuDetailsParams
باQueryProductDetailsParams
جایگزین کنید - برای استفاده از
BillingClient.querySkuDetailsAsync()
BillingClient.queryProductDetailsAsync()
تغییر دهید
توجه داشته باشید که نتایج پرس و جو اکنون به جای SkuDetails
ProductDetails
هستند. هر مورد ProductDetails
حاوی اطلاعات مربوط به محصول (شناسه، عنوان، نوع و غیره) است. برای محصولات اشتراک، ProductDetails
حاوی List<ProductDetails.SubscriptionOfferDetails>
است که لیست جزئیات پیشنهاد اشتراک است. برای محصولات یک بار خرید، ProductDetails
حاوی ProductDetails.OneTimePurchaseOfferDetails
است. از اینها می توان برای تصمیم گیری اینکه کدام پیشنهادها به کاربران نشان داده شود استفاده کرد.
مثال زیر نشان می دهد که برنامه شما قبل و بعد از انجام این تغییرات چگونه ممکن است ظاهر شود:
قبل از
کاتلین
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 }
جاوا
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. } } );
بعد از
کاتلین
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 }
جاوا
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 از اشیاء جدید (اشتراکها، طرحهای پایه، پیشنهادات و غیره) پشتیبانی نمیکنند، سیستم جدید هر SKU اشتراک را به یک طرح و پیشنهاد پایه سازگار با عقبتر ترجمه میکند. محصولات یکبار خرید موجود نیز به یک شی ProductDetails
منتقل می شوند. جزئیات پیشنهاد یک محصول خرید یک بار مصرف را می توان با روش getOneTimePurchaseOfferDetails()
مشاهده کرد.
به ندرت، برخی از دستگاهها نمیتوانند از ProductDetails
و queryProductDetailsAsync()
پشتیبانی کنند، معمولاً به دلیل نسخههای قدیمی سرویسهای Google Play . برای اطمینان از پشتیبانی مناسب از این سناریو، قبل از فراخوانی queryProductDetailsAsync
isFeatureSupported()
برای ویژگی PRODUCT_DETAILS
فراخوانی کنید. اگر پاسخ OK
باشد، دستگاه از این ویژگی پشتیبانی میکند و میتوانید با queryProductDetailsAsync()
تماس بگیرید. اگر پاسخ FEATURE_NOT_SUPPORTED
باشد، در عوض میتوانید لیست محصولات سازگار با عقب را با querySkuDetailsAsync()
درخواست کنید. برای کسب اطلاعات بیشتر درباره نحوه استفاده از ویژگیهای سازگاری با عقب، به راهنمای ویژگیهای اشتراک می 2022 مراجعه کنید.
جریان خرید پیشنهاد را راه اندازی کنید
راه اندازی یک جریان خرید برای یک پیشنهاد بسیار شبیه به راه اندازی یک جریان برای یک SKU است. برای شروع درخواست خرید با استفاده از نسخه 6، موارد زیر را انجام دهید:
- به جای استفاده از
SkuDetails
برایBillingFlowParams
، ازProductDetailsParams
استفاده کنید. - جزئیات پیشنهاد (ها) مانند شناسه پیشنهاد، شناسه طرح پایه و موارد دیگر را می توان با استفاده از شی
SubscriptionOfferDetails
به دست آورد.
برای خرید محصولی با پیشنهاد انتخابی کاربر، offerToken
پیشنهاد انتخابی را دریافت کرده و آن را در شیء ProductDetailsParams
ارسال کنید.
هنگامی که یک شی BillingFlowParams
ایجاد کردید، راهاندازی جریان صورتحساب با BillingClient
یکسان باقی میماند.
مثال زیر نشان می دهد که برنامه شما قبل و بعد از انجام این تغییرات چگونه ممکن است ظاهر شود:
قبل از
کاتلین
// 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)
جاوا
// 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)
بعد از
کاتلین
// 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)
جاوا
// 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 Billing Library 6 مانند نسخههای قبلی باقی میماند.
برای کشیدن تمام خریدهای فعال متعلق به کاربر و درخواست خریدهای جدید، موارد زیر را انجام دهید:
- به جای ارسال یک مقدار
BillingClient.SkuType
بهqueryPurchasesAsync()
، یک شیQueryPurchasesParams
را ارسال کنید که حاوی یک مقدارBillingClient.ProductType
است.
مثال زیر نشان می دهد که برنامه شما قبل و بعد از انجام این تغییرات چگونه ممکن است ظاهر شود:
قبل از
کاتلین
billingClient.queryPurchasesAsync(BillingClient.SkuType.SUBS) { billingResult, purchaseList -> { // Process the result } }
جاوا
billingClient.queryPurchasesAsync( BillingClient.SkuType.SUBS, new PurchasesResponseListener() { public void onQueryPurchasesResponse( BillingResult billingResult, List<Purchase> purchases) { // process the result } } );
بعد از
کاتلین
billingClient.queryPurchasesAsync( QueryPurchasesParams.newBuilder() .setProductType(BillingClient.ProductType.SUBS) .build() ) { billingResult, purchaseList -> // Process the result }
جاوا
billingClient.queryPurchasesAsync( QueryPurchasesParams.newBuilder().setProductType(ProductType.SUBS).build(), new PurchasesResponseListener() { public void onQueryPurchasesResponse( BillingResult billingResult, List<Purchase> purchases) { // Process the result } } );
مراحل مدیریت خریدهای خارج از برنامه و تراکنشهای معلق تغییر نکرده است.
وضعیت خرید اشتراک را با API جدید در باطن خود مدیریت کنید
شما باید جزء مدیریت وضعیت خرید اشتراکهای خود را در باطن خود منتقل کنید تا بتوانید خرید محصولات جدید ایجاد شده در مراحل قبلی را انجام دهید. جزء مدیریت وضعیت خرید اشتراکهای فعلی شما باید طبق معمول برای محصولات اشتراک تبدیلشدهای که قبل از راهاندازی می ۲۰۲۲ تعریف کردهاید کار کند، و برای مدیریت خرید پیشنهادات سازگار با گذشته کافی است، اما هیچ یک از عملکردهای جدید را پشتیبانی نمیکند.
شما باید API جدید خرید اشتراک را برای ماژول مدیریت وضعیت خرید اشتراک خود پیاده سازی کنید، که وضعیت خرید را بررسی می کند و حقوق اشتراک Play Billing را در باطن شما مدیریت می کند. نسخه قدیمی API تمام جزئیات لازم را برای مدیریت خریدها در پلتفرم جدید برنمیگرداند. برای جزئیات تغییرات نسبت به نسخههای قبلی، راهنمای ویژگیهای اشتراک جدید می 2022 را ببینید.
شما معمولاً هر بار که اعلان برنامهنویس زمان واقعی SubscriptionNotification
دریافت میکنید، با API خرید اشتراک تماس میگیرید تا آخرین اطلاعات مربوط به وضعیت اشتراک را دریافت کنید. باید تماسهای خود را با purchases.subscriptions.get
با نسخه جدید API خرید اشتراک، purchases.subscriptionsv2.get
جایگزین کنید. منبع جدیدی به نام SubscriptionPurchaseV2
وجود دارد که اطلاعات کافی برای مدیریت حق خرید برای اشتراکها در مدل جدید ارائه میکند.
این نقطه پایانی جدید وضعیت همه محصولات اشتراک و همه خریدهای شما را، بدون توجه به نسخه برنامه ای که آنها را فروخته است و زمانی که محصول تعریف شده است (قبل یا بعد از انتشار می 2022) را باز می گرداند، بنابراین پس از انتقال فقط به آن نیاز خواهید داشت. این نسخه از ماژول مدیریت وضعیت خرید اشتراک شما.
خریدهای اشتراک کاربر را تغییر دهید
در Play Billing Library نسخه 5 و نسخههای قبلی، از ProrationMode
برای اعمال تغییرات در خریدهای اشتراک کاربر، مانند ارتقا یا تنزل رتبه، استفاده میشد. این منسوخ شده و با ReplacementMode
در نسخه 6 جایگزین شده است.
کنترل تغییرات قیمت اشتراک
API launchPriceConfirmationFlow
که قبلاً منسوخ شده بود در Play Billing Library 6 حذف شده است. برای گزینههای جایگزین، راهنمای تغییرات قیمت را ببینید.
خطاهای Play Billing Library را مدیریت کنید
در Play Billing Library 6، یک کد NETWORK_ERROR
جدید اضافه شده است تا مشکلات اتصال شبکه بین دستگاه کاربر و سیستم Google Play را نشان دهد. همچنین تغییراتی در کدهای SERVICE_TIMEOUT
و SERVICE_UNAVAILABLE
وجود دارد. برای اطلاعات بیشتر، به بررسی کدهای پاسخ BillingResult مراجعه کنید.
رسیدگی به معاملات معلق
با شروع نسخه 6.0.0، کتابخانه صورتحساب Play شناسه سفارشی برای خریدهای معلق ایجاد نمیکند. برای این خریدها، شناسه سفارش پس از انتقال خرید به حالت PURCHASED
تکمیل می شود. مطمئن شوید که ادغام شما تنها پس از تکمیل کامل تراکنش، انتظار شناسه سفارش را دارد. همچنان می توانید از رمز خرید برای سوابق خود استفاده کنید. برای اطلاعات بیشتر در مورد رسیدگی به خریدهای معلق، به راهنمای ادغام کتابخانه صورتحساب Play و راهنمای مدیریت چرخه عمر خرید مراجعه کنید.