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

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

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

نظرة عامة

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

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

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

الترقية من الإصدار 7 أو 8 من PBL إلى الإصدار 9

للترقية من الإصدار 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 من PBL إلى الإصدار 9). عدِّل الـ تنفيذ طريقة queryProductDetailsAsync.

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

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

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

   الترقية من

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

   واجهة برمجة التطبيقات التي تم إيقافها نهائيًا سابقًا والتي تمت إزالتها	واجهة برمجة التطبيقات البديلة التي يجب استخدامها
   واجهات برمجة تطبيقات queryPurchaseHistoryAsync	الاطّلاع على مقالة طلب سجلّ الشراء إذا كنت تستخدم 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

   الترقية من

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

   واجهة برمجة التطبيقات التي تم إيقافها نهائيًا سابقًا والتي تمت إزالتها	واجهة برمجة التطبيقات البديلة التي يجب استخدامها
   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 Billing Library إعادة إنشاء اتصال الخدمة تلقائيًا إذا تم إجراء طلب بيانات من واجهة برمجة التطبيقات أثناء انقطاع اتصال الخدمة. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تفعيل ميزة إعادة الاتصال التلقائي بالخدمة.

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() قبل تحليل أهداف المتصفّح أو تشغيلها. على سبيل المثال:

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

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

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