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

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

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

نظرة عامة

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

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

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

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

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

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

    dependencies {
  def billing_version = "9.0.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.0.0"
  implementation("com.android.billingclient:billing-ktx:$billing_version")
}

  2. (لا ينطبق ذلك إلا على الترقية من الإصدار 7 من PBL إلى الإصدار 9 من PBL). عدِّل عملية تنفيذ طريقة 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 لعمليات الشراء النشطة أو المعلقة.
    • تتبَّع عمليات الشراء التي تم استهلاكها على خوادم الخلفية.
    • استخدِم واجهة 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. التعرّف على إعادة تصنيف رموز الخطأ

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

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

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

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

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

    Kotlin

    val linkUri = details.getLinkUri()
if (!linkUri.isNullOrEmpty()) {
  val intent = Intent(Intent.ACTION_VIEW, Uri.parse(linkUri))
  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);
}

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