يوضّح هذا المستند كيفية نقل البيانات من الإصدار 7 أو 8 من Google Play Billing Library (PBL) إلى الإصدار 9 من PBL، وكيفية دمج الميزات الجديدة.
للاطّلاع على قائمة كاملة بالتغييرات في الإصدار 9.0.0، يُرجى الرجوع إلى ملاحظات الإصدار.
مهارات Android
العرض على GitHubترقية Play Billing Library
android skills add play-billing-library-version-upgradeHelp me upgrade my Play Billing Library implementation.نظرة عامة
يتضمّن الإصدار 9 من PBL تحسينات على واجهات برمجة التطبيقات الحالية، بالإضافة إلى إزالة واجهات برمجة التطبيقات التي تم إيقافها نهائيًا في السابق. يقدّم هذا الإصدار من المكتبة أيضًا سياقًا أكثر ثراءً للأخطاء من خلال رموز الاستجابة الفرعية الجديدة.
التوافق مع الأنظمة القديمة لترقية PBL
للانتقال إلى الإصدار 9 من PBL، عليك تعديل بعض مراجع واجهة برمجة التطبيقات الحالية أو إزالتها من تطبيقك، كما هو موضّح في ملاحظات الإصدار وفي دليل نقل البيانات هذا لاحقًا.
الترقية من الإصدار 7 أو 8 من PBL إلى الإصدار 9 من PBL
للترقية من PBL 7 أو 8 إلى PBL 9، اتّبِع الخطوات التالية:
يُرجى تحديث إصدار 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") }(ينطبق ذلك فقط على الترقية من الإصدار 7 إلى الإصدار 9 من PBL). عدِّل طريقة تنفيذ
queryProductDetailsAsync.تم إجراء تغيير في توقيع طريقة
ProductDetailsResponseListener.onProductDetailsResponse، ما يتطلّب إجراء تغييرات في تطبيقك لتنفيذqueryProductDetailsAsync. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة عرض المنتجات المتاحة للشراء.التعامل مع واجهات برمجة التطبيقات التي تمت إزالتها
يسرد الجدول التالي واجهات برمجة التطبيقات التي تمت إزالتها وواجهات برمجة التطبيقات البديلة المقابلة التي يجب استخدامها في تطبيقك.
الترقية من
لم يعُد الإصدار 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 (إجراء يُنصح به) فعِّل إعادة الاتصال التلقائي بالخدمة.
يمكن أن تحاول Play Billing Library إعادة إنشاء اتصال الخدمة تلقائيًا في حال إجراء طلب بيانات من واجهة برمجة التطبيقات أثناء انقطاع اتصال الخدمة. لمزيد من المعلومات، يُرجى الاطّلاع على تفعيل إعادة الاتصال التلقائي بالخدمة.
التعامل مع رموز الاستجابة الفرعية الجديدة
ستتضمّن الآن BillingResult التي تم عرضها من
launchBillingFlow()حقل رمز استجابة فرعي. لن تتم تعبئة هذا الحقل إلا في بعض الحالات لتقديم سبب أكثر تحديدًا للفشل. يمكن أن يحتوي حقل الردّ الفرعي على القيم التالية:-
PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS: يتم عرض هذه الرسالة عندما يكون رصيد المستخدم أقل من سعر المنتج الذي يحاول شراءه. -
USER_INELIGIBLE: تظهر هذه الرسالة عندما لا يستوفي المستخدم متطلبات الأهلية التي تم ضبطها لعرض الاشتراك. -
NO_APPLICABLE_SUB_RESPONSE_CODE: القيمة التلقائية التي يتم عرضها في حال عدم توفّر أي رمز استجابة فرعي آخر
خطوة نقل البيانات: يجب تعديل طريقة معالجة نتائج
PurchasesUpdatedListenerأو ما يعادلها للتعرّف على رموز الاستجابة الفرعية المحدّدة هذه والاستجابة لها من أجل توفير تجربة أفضل للمستخدم. على سبيل المثال، يمكنك أن تطلب من المستخدم إصلاح طرق الدفع أو عرض رسالة خطأ معيّنة.-
الوعي بإعادة تصنيف رموز الخطأ
في الحالات التي يحظر فيها النظام تطبيق "متجر Google Play" (على سبيل المثال، في وضع الأطفال المخصّص من قِبل المصنّع الأصلي للجهاز)، تم تغيير رمز الاستجابة من PBL من
ERRORإلىBILLING_UNAVAILABLE.خطوة نقل البيانات: تأكَّد من أنّ منطق معالجة الأخطاء يتوافق مع هذا التغيير ولا يعتمد على تلقّي خطأ عام في هذه السيناريوهات المحدّدة.
التعامل مع إمكانية قبول القيم الفارغة في
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) }
Java
String linkUri = details.getLinkUri(); if (!android.text.TextUtils.isEmpty(linkUri)) { Intent intent = new Intent(Intent.ACTION_VIEW, Uri.parse(linkUri)); context.startActivity(intent); }تغييرات اختيارية
إتاحة عمليات الشراء المُعلّقة لخطط الدفع المُسبَق. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة التعامل مع الاشتراكات والمعاملات في انتظار المعالجة.
اشتراكات الأقساط الافتراضية لمزيد من المعلومات، يُرجى الاطّلاع على مقالة دمج الاشتراكات بالتقسيط.