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

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

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

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

Help me upgrade my Play Billing Library implementation.

نمای کلی

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

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

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

از 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. (فقط برای ارتقا از «کتابخانه خدمات صورت‌حساب Play» نسخه ۷ به «کتابخانه خدمات صورت‌حساب Play» نسخه ۹ قابل‌اعمال است). پیاده‌سازی روش queryProductDetailsAsync را به‌روز کنید.

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

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

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

   ارتقا دادن از

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

   میانای برنامه‌سازی کاربردی قبلاً نامناسب برداشته شد	میانای برنامه‌سازی کاربردی جایگزین برای استفاده
   میاناهای برنامه‌سازی کاربردی queryPurchaseHistoryAsync	سابقه خرید پُرسمان را ببینید. اگر از queryPurchaseHistoryAsync برای تعیین واجدشرایط بودن برای دوره‌های آزمایشی رایگان استفاده می‌کردید، اکنون باید از ProductDetails.getSubscriptionOfferDetails() برای تعیین اینکه کاربر واجدشرایط کدام پیشنهادهای ویژه است استفاده کنید.
   BillingClient.SkuType	BillingClient.ProductType. ثابت‌های نوع محصول INAPP و SUBS ازنظر عملکردی مشابه ثابت‌های نوع SKU منسوخ‌شده باقی می‌مانند.
   SkuDetails	ProductDetails. این مدل داده جدیدی است که از محصولات یک‌باره پشتیبانی می‌کند.
   SkuDetailsParams	از QueryProductDetailsParams با queryProductDetailsAsync استفاده کنید.
   SkuDetailsResponseListener	از ProductDetailsResponseListener با queryProductDetailsAsync استفاده کنید.
   QueryPurchaseHistoryParams	از queryPurchasesAsync برای خریدهای فعال یا معلقه استفاده کنید. خریدهای مصرف‌شده را در سرورهای نهایی‌تان ردیابی کنید. برای خریدهای لغوشده یا باطل‌شده، از میانای برنامه‌سازی کاربردی خریدهای باطل‌شده سمت سرور استفاده کنید.
   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 استفاده کنید. خریدهای مصرف‌شده را در سرورهای نهایی‌تان ردیابی کنید. برای خریدهای لغوشده یا باطل‌شده، از میانای برنامه‌سازی کاربردی خریدهای باطل‌شده سمت سرور استفاده کنید.
   getSkuDetailsList و setSkuDetailsList	از BillingFlowParams.Builder.setProductDetailsParamsList استفاده کنید

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

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

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

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

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

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

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

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

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

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. تغییرات اختیاری.

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

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