انتقال به «کتابخانه خدمات صورت‌حساب 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	Query Purchase History را ببینید. اگر از 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. تغییرات اختیاری.

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

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