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

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

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

مهارات Android

العرض على GitHub

ترقية Play Billing Library

استخدِم مهارة Android في Play Billing Library لإجراء الترقية تلقائيًا إلى أحدث إصدار.

لتثبيت المهارة من Android CLI، شغِّل:

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

لتفعيل المهارة، جرِّب الطلب التالي:

Help me upgrade my Play Billing Library implementation.

نظرة عامة

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

التوافق مع الأنظمة القديمة لترقية PBL

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

الترقية من الإصدار 7 أو 8 من PBL إلى الإصدار 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، فإنّ وحدة KTX في Google Play Billing Library تحتوي على إضافات 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 من PBL). عدِّل طريقة تنفيذ queryProductDetailsAsync.

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

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

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

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

   الترقية من

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

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

   الترقية من

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

   إزالة واجهة برمجة التطبيقات التي تم إيقافها نهائيًا سابقًا	واجهة برمجة تطبيقات بديلة للاستخدام
   BillingClient.SkuType	BillingClient.ProductType: تظل ثوابت نوع المنتج INAPP وSUBS مشابهة من الناحية الوظيفية لثوابت نوع رمز التخزين التعريفي التي تم إيقافها نهائيًا.
   SkuDetails	ProductDetails: هذا هو نموذج البيانات الجديد الذي يتيح المنتجات المدفوعة لمرة واحدة.
   SkuDetailsParams	استخدِم QueryProductDetailsParams مع queryProductDetailsAsync.
   SkuDetailsResponseListener	استخدِم ProductDetailsResponseListener مع queryProductDetailsAsync.
   QueryPurchaseHistoryParams	استخدِم queryProductDetailsAsync لعمليات الشراء النشطة أو المعلّقة. تتبُّع عمليات الشراء المستهلكة على خوادم الخلفية استخدِم Voided Purchases API من جهة الخادم لعمليات الشراء المُلغاة أو الباطلة.
   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.

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

   ملاحظة: لكي تعمل هذه الميزة، يجب استخدام الإصدار 1.9 أو إصدار أحدث من مكتبة AndroidX.core.

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

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

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