از نسخه‌های ۷ یا ۸ به کتابخانه پرداخت گوگل پلی ۹ مهاجرت کنید

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

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

نمای کلی

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

سازگاری با نسخه‌های قبلی برای ارتقاء PBL

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

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

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

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

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

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

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

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

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

  3. API های حذف شده را مدیریت کنید.

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

    ارتقا از

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

    API منسوخ‌شده قبلی حذف شد API جایگزین برای استفاده
    APIهای همگام‌سازی نشده‌ی queryPurchaseHistory به بخش «سوال تاریخچه خرید» مراجعه کنید. اگر قبلاً از queryPurchaseHistoryAsync برای تعیین واجد شرایط بودن برای دوره‌های آزمایشی رایگان استفاده می‌کردید، اکنون باید از ProductDetails.getSubscriptionOfferDetails() برای تعیین پیشنهادهایی که کاربر واجد شرایط دریافت آنهاست، استفاده کنید.
    نوع مشتری صورتحساب BillingClient.ProductType . ثابت‌های نوع محصول INAPP و SUBS از نظر عملکردی مشابه ثابت‌های نوع SKU منسوخ شده باقی می‌مانند.
    جزئیات Sku جزئیات محصول . این مدل داده جدیدی است که از محصولات یکبار مصرف پشتیبانی می‌کند.
    پارامترهای SkuDetails از QueryProductDetailsParams به همراه queryProductDetailsAsync استفاده کنید.
    SkuDetailsResponseListener از ProductDetailsResponseListener به همراه queryProductDetailsAsync استفاده کنید.
    پارامترهای تاریخچه خرید پرس و جو
    • برای خریدهای فعال یا در انتظار، از queryPurchasesAsync استفاده کنید.
    • خریدهای مصرف‌شده را در سرورهای backend خود پیگیری کنید.
    • برای خریدهای لغو شده یا باطل شده، از API خریدهای باطل شده سمت سرور استفاده کنید.
    getSkuDetailsList و setSkuDetailsList از BillingFlowParams.Builder.setProductDetailsParamsList استفاده کنید
    querySkuDetailsAsync queryProductDetailsAsync
    enablePendingPurchases() (API بدون پارامتر) enablePendingPurchases(پارامترهای PendingPurchasesParams)
    توجه داشته باشید که تابع منسوخ‌شده‌ی enablePendingPurchases() از نظر عملکردی معادل enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) .
    queryPurchasesAsync(String skuType, PurchasesResponseListener listener) queryPurchasesAsync

    ارتقا از

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

    API منسوخ‌شده قبلی حذف شد API جایگزین برای استفاده
    نوع مشتری صورتحساب BillingClient.ProductType . ثابت‌های نوع محصول INAPP و SUBS از نظر عملکردی مشابه ثابت‌های نوع SKU منسوخ شده باقی می‌مانند.
    جزئیات Sku جزئیات محصول . این مدل داده جدیدی است که از محصولات یکبار مصرف پشتیبانی می‌کند.
    پارامترهای SkuDetails از QueryProductDetailsParams به همراه queryProductDetailsAsync استفاده کنید.
    SkuDetailsResponseListener از ProductDetailsResponseListener به همراه queryProductDetailsAsync استفاده کنید.
    پارامترهای تاریخچه خرید پرس و جو
    • برای خریدهای فعال یا در انتظار، از queryProductDetailsAsync استفاده کنید.
    • خریدهای مصرف‌شده را در سرورهای backend خود پیگیری کنید.
    • برای خریدهای لغو شده یا باطل شده، از API خریدهای باطل شده سمت سرور استفاده کنید.
    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 Store توسط سیستم مسدود شده است (برای مثال، در حالت کودکان سفارشی‌سازی‌شده توسط OEM)، کد پاسخ از PBL از ERROR به BILLING_UNAVAILABLE تغییر کرده است.

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

  7. مدیریت nullability DeveloperProvidedBillingDetails.getLinkUri() .

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

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

    کاتلین 

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  context.startActivity(intent)
}

    جاوا 

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

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