نقل البيانات من الإصدار 7 أو 8 إلى الإصدار 9 من Google Play Billing Library

يوضّح هذا المستند كيفية نقل البيانات من الإصدار 7 أو 8 من Google Play Billing Library (PBL) إلى الإصدار 9، وكيفية الدمج مع الميزات الجديدة.

للاطّلاع على القائمة الكاملة بالتغييرات في الإصدار 9.0.0، يُرجى الرجوع إلى ملاحظات الإصدار.

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

Help me upgrade my Play Billing Library implementation.

نظرة عامة

يتضمّن الإصدار 9 من PBL تحسينات على واجهات برمجة التطبيقات الحالية، بالإضافة إلى إزالة واجهات برمجة التطبيقات التي تم إيقافها نهائيًا. يقدّم هذا الإصدار من المكتبة أيضًا سياقًا أكثر تفصيلاً للأخطاء من خلال رموز الاستجابة الفرعية الجديدة.

التوافق مع الإصدارات القديمة عند ترقية PBL

لنقل البيانات إلى الإصدار 9 من Play Billing Library، عليك تعديل بعض مراجع واجهة برمجة التطبيقات الحالية أو إزالتها من تطبيقك، كما هو موضّح في ملاحظات الإصدار وفي وقت لاحق في دليل نقل البيانات هذا.

الترقية من الإصدار 7 أو 8 من "مكتبة Play Billing" إلى الإصدار 9

لترقية الإصدار من PBL 7 أو 8 إلى PBL 9، اتّبِع الخطوات التالية:

1. عدِّل إصدار التبعية في Play Billing Library في ملف build.gradle الخاص بتطبيقك.

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

   إذا كنت تستخدم Kotlin، يحتوي وحدة Google Play Billing Library KTX على إضافات Kotlin وإمكانية استخدام إجراءات فرعية تتيح لك كتابة رمز Kotlin اصطلاحي عند استخدام Google Play Billing Library. لتضمين هذه الإضافات في مشروعك، أضِف التبعية التالية إلى ملف build.gradle في تطبيقك كما هو موضّح:

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

2. (ينطبق ذلك فقط على الترقية من الإصدار 7 إلى الإصدار 9 من Play Billing Library). عدِّل تنفيذ طريقة queryProductDetailsAsync.

   هناك تغيير في توقيع الطريقة ProductDetailsResponseListener.onProductDetailsResponse، ما يتطلّب إجراء تغييرات في تطبيقك لتنفيذ queryProductDetailsAsync. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة عرض المنتجات المتاحة للشراء.

3. التعامل مع واجهات برمجة التطبيقات التي تمت إزالتها

   يسرد الجدول التالي واجهات برمجة التطبيقات التي تمت إزالتها وواجهات برمجة التطبيقات البديلة التي يجب استخدامها في تطبيقك.

   الترقية من

   لم يعُد الإصدار 9 من PBL يتيح استخدام واجهات برمجة التطبيقات المُدرَجة في الجدول التالي. إذا كان تطبيقك يستخدم أيًا من واجهات برمجة التطبيقات التي تمت إزالتها، يُرجى الرجوع إلى الجدول لمعرفة واجهات برمجة التطبيقات البديلة المناسبة لها.

   إزالة واجهة برمجة التطبيقات المتوقّفة نهائيًا	واجهة برمجة التطبيقات البديلة التي يجب استخدامها
   واجهات برمجة التطبيقات queryPurchaseHistoryAsync	اطّلِع على سجلّ عمليات الشراء المتعلقة بطلبات البحث. إذا كنت تستخدم طريقة queryPurchaseHistoryAsync لتحديد الأهلية للاستفادة من الفترات التجريبية المجانية، عليك الآن استخدام طريقة ProductDetails.getSubscriptionOfferDetails() لتحديد العروض التي يكون المستخدم مؤهلاً للاستفادة منها.
   BillingClient.SkuType	‫BillingClient.ProductType ستظلّ ثوابت نوع المنتج INAPP وSUBS مشابهة من الناحية الوظيفية لثوابت نوع رمز التخزين التعريفي المتوقّفة نهائيًا.
   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

   الترقية من

   يسرد الجدول التالي واجهات برمجة التطبيقات التي تمت إزالتها في الإصدار 9 من PBL، وواجهات برمجة التطبيقات البديلة التي يجب استخدامها في تطبيقك.

   إزالة واجهة برمجة التطبيقات المتوقّفة نهائيًا	واجهة برمجة التطبيقات البديلة التي يجب استخدامها
   BillingClient.SkuType	‫BillingClient.ProductType ستظلّ ثوابت نوع المنتج INAPP وSUBS مشابهة من الناحية الوظيفية لثوابت نوع رمز التخزين التعريفي المتوقّفة نهائيًا.
   SkuDetails	ProductDetails هذا هو نموذج البيانات الجديد الذي يتيح المنتجات التي يتم شراؤها لمرة واحدة.
   SkuDetailsParams	استخدِم QueryProductDetailsParams مع queryProductDetailsAsync.
   SkuDetailsResponseListener	استخدِم ProductDetailsResponseListener مع queryProductDetailsAsync.
   QueryPurchaseHistoryParams	استخدِم queryProductDetailsAsync لعمليات الشراء النشطة أو التي تنتظر المراجعة. تتبُّع عمليات الشراء المستهلكة على خوادم الخلفية استخدِم واجهة برمجة التطبيقات لعمليات الشراء الملغاة من جهة الخادم لعمليات الشراء الملغاة أو الباطلة.
   getSkuDetailsList وsetSkuDetailsList	استخدِم BillingFlowParams.Builder.setProductDetailsParamsList

4. (يُفضّل) تفعيل ميزة إعادة الاتصال التلقائي بالخدمة

   يمكن أن تحاول مكتبة Play Billing Library إعادة إنشاء اتصال الخدمة تلقائيًا إذا تم إجراء طلب بيانات من واجهة برمجة التطبيقات أثناء انقطاع الاتصال بالخدمة. لمزيد من المعلومات، يُرجى الاطّلاع على تفعيل إعادة الاتصال التلقائي بالخدمة.

5. التعامل مع رموز الردود الفرعية الجديدة

   سيتضمّن BillingResult الذي تم عرضه من launchBillingFlow() الآن حقل رمز استجابة فرعي. لن يتم ملء هذا الحقل إلا في بعض الحالات لتقديم سبب أكثر تحديدًا لتعذُّر إكمال العملية. يمكن أن يحتوي حقل الردّ الفرعي على القيم التالية:

   • ‫PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS: يتم عرض هذا الرمز عندما تكون أموال المستخدم أقل من سعر السلعة التي يحاول شراءها.
   • ‫USER_INELIGIBLE: يتم عرض هذا الرمز عندما لا يستوفي المستخدم متطلبات الأهلية المحدّدة لعرض اشتراك.
   • NO_APPLICABLE_SUB_RESPONSE_CODE: القيمة التلقائية التي يتم عرضها عندما لا يكون أي رمز استجابة فرعية آخر منطبقًا.

   خطوة النقل: عدِّل طريقة معالجة الرمز PurchasesUpdatedListener أو الرمز المكافئ للتعرّف على رموز الاستجابة الفرعية المحدّدة هذه والردّ عليها من أجل تقديم تجربة أفضل للمستخدم. على سبيل المثال، يُطلب منك إصلاح طرق الدفع أو تظهر لك رسالة خطأ معيّنة.

6. التعرّف على إعادة تصنيف رمز الخطأ

   في الحالات التي يحظر فيها النظام تطبيق "متجر Google Play" (على سبيل المثال، في وضع الأطفال المخصّص من المصنّع الأصلي للجهاز)، تم تغيير رمز الاستجابة من PBL من ERROR إلى BILLING_UNAVAILABLE.

   خطوة النقل: تأكَّد من أنّ منطق معالجة الأخطاء يتوافق مع هذا التغيير ولا يعتمد على تلقّي خطأ عام في هذه السيناريوهات المحدّدة.

7. تعامَل مع DeveloperProvidedBillingDetails.getLinkUri() إمكانية قبول القيم الفارغة.

   إذا كنت تستخدم DeveloperProvidedBillingDetails كجزء من عملية دمج مع نظام دفع خارجي، سيصبح getLinkUri() الآن @Nullable.

   خطوة النقل: للتعامل مع هذا التغيير بأمان، تأكَّد من أنّ رمز الدمج يتعامل مع القيمتَين null والسلسلة الفارغة ("") من الطريقة DeveloperProvidedBillingDetails.getLinkUri() قبل تحليل أو تشغيل نوايا المتصفح. على سبيل المثال:

   Kotlin

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

   Java

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

8. التغييرات الاختيارية

   • إتاحة عمليات الشراء المعلقة للخطط المدفوعة مسبقًا. لمزيد من المعلومات، اطّلِع على مقالة التعامل مع الاشتراكات والمعاملات المعلقة.

   • الاشتراكات في خطط الأقساط الافتراضية لمزيد من المعلومات، يُرجى الاطّلاع على مقالة دمج الاشتراكات بالتقسيط.