انتقال به «کتابخانه خدمات صورت‌حساب Google Play» نسخه ۹ از نسخه‌های ۷ یا ۸

این سند نحوه انتقال از «کتابخانه خدمات صورت‌حساب Google Play» (PBL) نسخه ۷ یا ۸ به PBL نسخه ۹ و نحوه ادغام با ویژگی‌های جدید را شرح می‌دهد.

برای مشاهده فهرست کامل تغییرات در نسخه ۹.۰.۰، به یادداشت‌های انتشار مراجعه کنید.

مهارت‌های Android

مشاهده در GitHub

ارتقا دادن «کتابخانه خدمات صورت‌حساب Play»

از مهارت Android «کتابخانه خدمات صورت‌حساب Play» برای خودکارسازی ارتقا به جدیدترین نسخه استفاده کنید.

برای نصب مهارت از Android CLI، این دستور را اجرا کنید:

android skills add play-billing-library-version-upgrade

برای فعال کردن مهارت، پیام‌واره زیر را امتحان کنید:

Help me upgrade my Play Billing Library implementation.

نمای کلی

‫PBL 9 حاوی بهبودهایی در میاناهای برنامه‌سازی کاربردی موجود و همچنین حذف میاناهای برنامه‌سازی کاربردی منسوخ‌شده قبلی است. این نسخه از کتابخانه همچنین بافت خطای غنی‌تری را ازطریق کدهای زیرپاسخ جدید معرفی می‌کند.

سازگاری با نسخه قدیمی برای ارتقای PBL

برای انتقال به PBL 9، باید برخی‌از مراجع میانای برنامه‌سازی کاربردی موجود را در برنامه‌تان به‌روزرسانی یا حذف کنید، همان‌طور که در یادداشت‌های انتشار و در ادامه این راهنمای انتقال شرح داده شده است.

ارتقا از PBL 7 یا 8 به PBL 9

برای ارتقا دادن از PBL 7 یا 8 به PBL 9، مراحل زیر را انجام دهید:

1. نسخه وابستگی «کتابخانه خدمات صورت‌حساب Play» را در فایل build.gradle برنامه‌تان به‌روز کنید.

   dependencies {
     def billing_version = "9.1.0"
     implementation "com.android.billingclient:billing:$billing_version"
   }
   

   اگر از Kotlin استفاده می‌کنید، ماژول KTX «کتابخانه خدمات صورت‌حساب Google Play» حاوی افزونه‌های Kotlin و پشتیبانی از کوروتین‌ها است که به شما امکان می‌دهد هنگام استفاده از «کتابخانه خدمات صورت‌حساب Google Play»، Kotlin اصطلاحی بنویسید. برای گنجاندن این افزونه‌ها در پروژه‌تان، وابستگی زیر را به فایل build.gradle برنامه‌تان اضافه کنید:

   dependencies {
     val billing_version = "9.1.0"
     implementation("com.android.billingclient:billing-ktx:$billing_version")
   }
   

2. (فقط برای ارتقا از PBL 7 به PBL 9 قابل‌اجرا است). پیاده‌سازی روش queryProductDetailsAsync را به‌روز کنید.

   تغییری در امضای روش ProductDetailsResponseListener.onProductDetailsResponse ایجاد شده است که مستلزم تغییراتی در برنامه‌تان برای پیاده‌سازی queryProductDetailsAsync است. برای اطلاعات بیشتر، به نمایش محصولات موجود برای خرید مراجعه کنید.

3. میاناهای برنامه‌سازی کاربردی برداشته‌شده را مدیریت کنید.

   نکته: برای مدیریت میاناهای برنامه‌سازی کاربردی برداشته‌شده، می‌توانید از مهارت ارتقای نسخه کتابخانه خدمات صورت‌حساب Play استفاده کنید. این مهارت برای ساده‌سازی انتقال شما از الگوهای قدیمی به جدیدترین استانداردهای PBL طراحی شده است. با شناسایی خودکار فراخوانی‌های روش قدیمی، این مهارت توصیه‌های دقیقی برای به‌روزرسانی پیاده‌سازی شما به جدیدترین استانداردها ارائه می‌دهد.

   جدول زیر میاناهای برنامه‌سازی کاربردی حذف‌شده و میاناهای برنامه‌سازی کاربردی جایگزین مربوطه را که باید در برنامه‌تان استفاده کنید فهرست می‌کند.

   ارتقا دادن از

   PBL 9 دیگر از میاناهای برنامه‌سازی کاربردی فهرست‌شده در جدول زیر پشتیبانی نمی‌کند. اگر پیاده‌سازی شما از هرکدام از این میاناهای برنامه‌سازی کاربردی حذف‌شده استفاده می‌کند، برای میاناهای برنامه‌سازی کاربردی جایگزین مربوطه به جدول مراجعه کنید.

   میانای برنامه‌سازی کاربردی منسوخ‌شده قبلی برداشته شد	میانای برنامه‌سازی کاربردی جایگزین برای استفاده
   queryPurchaseHistoryAsync APIs	پرس‌وجو کردن سابقه خرید را ببینید. اگر از queryPurchaseHistoryAsync برای تعیین واجدشرایط بودن برای دوره‌های آزمایشی رایگان استفاده می‌کردید، اکنون باید از ProductDetails.getSubscriptionOfferDetails() استفاده کنید تا مشخص شود کاربر واجدشرایط کدام پیشنهادهای ویژه است.
   BillingClient.SkuType	BillingClient.ProductType. ثابت‌های نوع محصول INAPP و SUBS ازنظر عملکردی مشابه ثابت‌های نوع SKU منسوخ‌شده باقی می‌مانند.
   SkuDetails	ProductDetails. این مدل داده جدیدی است که از محصولات یک‌باره پشتیبانی می‌کند.
   SkuDetailsParams	از QueryProductDetailsParams با queryProductDetailsAsync استفاده کنید.
   SkuDetailsResponseListener	از ProductDetailsResponseListener با queryProductDetailsAsync استفاده کنید.
   QueryPurchaseHistoryParams	از queryPurchasesAsync برای خریدهای فعال یا معلقه استفاده کنید. خریدهای مصرف‌شده را در سرورهای نهایی‌تان ردگیری کنید. برای خریدهای لغوشده یا باطل‌شده، از Voided Purchases API در سمت سرور استفاده کنید.
   getSkuDetailsList و setSkuDetailsList	از BillingFlowParams.Builder.setProductDetailsParamsList استفاده کنید
   querySkuDetailsAsync	queryProductDetailsAsync
   enablePendingPurchases() (میانای برنامه‌سازی کاربردی بدون پارامتر)	enablePendingPurchases(PendingPurchasesParams params) توجه داشته باشید که enablePendingPurchases()‎ منسوخ‌شده ازنظر عملکردی معادل enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) است.
   queryPurchasesAsync(String skuType, PurchasesResponseListener listener)	queryPurchasesAsync

   ارتقا دادن از

   جدول زیر میاناهای برنامه‌سازی کاربردی را که در PBL 9 برداشته شده‌اند و میاناهای برنامه‌سازی کاربردی جایگزین مربوطه را که باید در برنامه‌تان استفاده کنید فهرست می‌کند.

   میانای برنامه‌سازی کاربردی منسوخ‌شده قبلی برداشته شد	میانای برنامه‌سازی کاربردی جایگزین برای استفاده
   BillingClient.SkuType	BillingClient.ProductType. ثابت‌های نوع محصول INAPP و SUBS ازنظر عملکردی مشابه ثابت‌های نوع SKU منسوخ‌شده باقی می‌مانند.
   SkuDetails	ProductDetails. این مدل داده جدیدی است که از محصولات یک‌باره پشتیبانی می‌کند.
   SkuDetailsParams	از QueryProductDetailsParams با queryProductDetailsAsync استفاده کنید.
   SkuDetailsResponseListener	از ProductDetailsResponseListener با queryProductDetailsAsync استفاده کنید.
   QueryPurchaseHistoryParams	از queryProductDetailsAsync برای خریدهای فعال یا معلقه استفاده کنید. خریدهای مصرف‌شده را در سرورهای نهایی‌تان ردگیری کنید. برای خریدهای لغوشده یا باطل‌شده، از Voided Purchases API در سمت سرور استفاده کنید.
   getSkuDetailsList و setSkuDetailsList	از BillingFlowParams.Builder.setProductDetailsParamsList استفاده کنید

4. (توصیه‌شده) اتصال مجدد خودکار سرویس را فعال کنید.

   اگر درحالی‌که سرویس قطع است فراخوانی میانای برنامه‌سازی کاربردی انجام شود، «کتابخانه صورت‌حساب Play» می‌تواند تلاش کند اتصال سرویس را به‌طور خودکار دوباره برقرار کند. برای اطلاعات بیشتر، فعال کردن اتصال مجدد خودکار سرویس را ببینید.

5. کدهای زیرپاسخ جدید را مدیریت کنید.

   BillingResult برگردانده‌شده از launchBillingFlow() اکنون شامل فیلد کد زیرپاسخ خواهد بود. این فیلد فقط در برخی موارد پر می‌شود تا دلیل مشخص‌تری برای ناموفق بودن ارائه دهد. فیلد زیرپاسخ می‌تواند مقادیر زیر را داشته باشد:

   • PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS - زمانی برگردانده می‌شود که موجودی کاربر کمتر از قیمت محصولی باشد که می‌خواهد بخرد.
   • USER_INELIGIBLE - زمانی برگردانده می‌شود که کاربر الزامات واجدشرایط بودن پیکربندی‌شده برای پیشنهاد اشتراک را نداشته باشد.
   • NO_APPLICABLE_SUB_RESPONSE_CODE - مقدار پیش‌فرض، زمانی برگردانده می‌شود که هیچ کد زیرپاسخ دیگری قابل‌اعمال نباشد.

   مرحله انتقال: PurchasesUpdatedListener یا مدیریت نتیجه معادل آن را به‌روز کنید تا این کدهای زیرپاسخ خاص را تشخیص دهد و به آن‌ها پاسخ دهد تا تجربه کاربری بهتری ارائه شود. برای مثال، از کاربر بخواهید روش‌های پرداخت را اصلاح کند یا پیام خطای خاصی را نشان دهد.

6. آگاهی از طبقه‌بندی مجدد کد خطا.

   در مواردی که برنامه «فروشگاه Play» توسط سیستم مسدود شده است (برای مثال، در حالت کودک سفارشی‌سازی‌شده OEM)، کد پاسخ از PBL از ERROR به BILLING_UNAVAILABLE تغییر کرده است.

   مرحله انتقال: مطمئن شوید که منطق رسیدگی به خطای شما این تغییر را دربرمی‌گیرد و در این سناریوهای خاص به دریافت خطای عمومی متکی نیست.

   توجه: برای اینکه این ویژگی کار کند، به کتابخانه AndroidX.core نسخه ۱.۹ یا بالاتر نیاز دارید.

7. مدیریت کردن پوچ‌پذیری DeveloperProvidedBillingDetails.getLinkUri().

   اگر از DeveloperProvidedBillingDetails به‌عنوان بخشی از ادغام پرداخت‌های خارجی استفاده می‌کنید، getLinkUri() اکنون @Nullable است.

   مرحله انتقال: برای مدیریت ایمن این تغییر، مطمئن شوید که کد ادغام شما هم مقادیر null و هم مقادیر رشته خالی ("") را از روش DeveloperProvidedBillingDetails.getLinkUri() قبل‌از تجزیه یا راه‌اندازی هدف‌های مرورگر مدیریت می‌کند. برای مثال:

   کاتلین

   val linkUri = details.linkUri
   if (!linkUri.isNullOrEmpty()) {
       val intent = Intent(Intent.ACTION_VIEW, linkUri.toUri())
       context.startActivity(intent)
   }
   MigrateGpblv9.kt

   جاوا

   String linkUri = details.getLinkUri();
   if (!android.text.TextUtils.isEmpty(linkUri)) {
     Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri));
     context.startActivity(intent);
   }
   

8. تغییرات اختیاری.

   • پشتیبانی از خریدهای معلقه برای طرح‌های پیش‌پرداخت. برای اطلاعات بیشتر، به مدیریت اشتراک‌ها و تراکنش‌های معلقه مراجعه کنید.

   • اشتراک‌های قسط مجازی. برای اطلاعات بیشتر، ادغام اشتراک‌های قسطی را ببینید.