ملاحظات إصدار Google Play Billing Library

يحتوي هذا المستند على ملاحظات الإصدار لمجموعة "مكتبة الفوترة في Google Play".

إصدار Google Play Billing Library 7.1.1 ‏ (‎03/10/2024)

أصبح الإصدار 7.1.1 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

إصلاح الأخطاء

الإصدار 7.1.0 من Google Play Billing Library ‏ (‎19/09/2024)

أصبح الإصدار 7.1.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

  • أمان مُحسَّن للخيوط المتعلّقة بحالة الاتصال وإدارته
  • تمّت إضافة تغييرات جزئية لاختبار رموز الاستجابة BillingResult التي تمّ إصدارها بالكامل في الإصدار 7.1.1 من Play Billing Library. لاختبار دمجك باستخدام هذه الميزة، عليك الترقية إلى الإصدار 7.1.1 من مكتبة Google Play Billing Library. هناك خطأ سيؤثّر فقط في التطبيقات التي تم فيها تفعيل اختبار عمليات إلغاء الفوترة، ولن يؤثّر في الاستخدام العادي. لمزيد من المعلومات، يُرجى الاطّلاع على رموز استجابة اختبار BillingResult.

إصدار Google Play Billing Library 7.0.0 (‎14/05/2024)

أصبح الإصدار 7.0.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

الإصدار 6.2.1 من Google Play Billing Library ‏ (‎16/04/2024)

أصبح الإصدار 6.2.1 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

إصدار Google Play Billing Library 6.2.0 (‎06/03/2024)

أصبح الإصدار 6.2.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

إصدار Google Play Billing Library 6.1.0 ‏ (‎14/11/2023)

أصبح الإصدار 6.1.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

إصدار 6.0.1 من Google Play Billing Library‏ (‎22/06/2023)

أصبح الإصدار 6.0.1 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

عليك تحديث Play Billing Library لتكون متوافقة مع Android 14.

الإصدار 6.0 من Google Play Billing Library‏ (‎10/05/2023)

أصبح الإصدار 6.0.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

  • تمت إضافة فهرس جديد ReplacementMode للاستبدال ProrationMode.

    يُرجى العلم أنّ الإصدار ProrationMode لا يزال متاحًا لأسباب تتعلّق بالتوافق مع الإصدارات القديمة.

  • تمّت إزالة معرّف الطلب لعمليات شراء PENDING.

    في السابق، كان يتم إنشاء معرّف الطلب دائمًا حتى إذا كانت عملية الشراء في انتظار المراجعة. اعتبارًا من الإصدار 6.0.0، لن يتم إنشاء معرّف طلب لعمليات الشراء المعلّقة، وسيتم ملء معرّف الطلب لهذه عمليات الشراء بعد نقل عملية الشراء إلى الحالة PURCHASED.

  • تمّت إزالة الطريقتَين queryPurchases وlaunchPriceConfirmationFlow.

    تمّت إزالة الطريقتَين queryPurchases وlaunchPriceConfirmationFlow اللتين تم وضع علامة "متوقفة نهائيًا" عليهما في السابق من مكتبة queryPurchasesBilling Library 6.0.0. على المطوّرين استخدام queryPurchasesAsync بدلاً من queryPurchases. للاطّلاع على بدائل launchPriceConfirmationFlow، يُرجى الاطّلاع على التغييرات في الأسعار.

  • تمت إضافة رمز استجابة جديد لخطأ الشبكة.

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

  • تم تعديل SERVICE_UNAVAILABLE و SERVICE_TIMEOUT.

    بدءًا من الإصدار 6.0.0 من PBL، سيتم عرض الأخطاء الناتجة عن انتهاء مهلة المعالجة برمز SERVICE_UNAVAILABLE بدلاً من الرمز الحالي SERVICE_TIMEOUT.

    لا يتغيّر السلوك في الإصدارات السابقة من "الإعلانات الصورية".

  • تمت إزالة SERVICE_TIMEOUT.

    بدءًا من الإصدار 6.0.0 من PBL، لن يتم عرض SERVICE_TIMEOUT. ستظلّ النُسخ السابقة من ملف PBL تعرِض هذا الرمز.

  • تمت إضافة تسجيل إضافي.

    يتضمّن الإصدار 6 من Play Billing Library ميزة تسجيل إضافية، ما يقدّم تحليلاً بشأن استخدام واجهة برمجة التطبيقات (مثل حالات النجاح والفشل) ومشاكل ربط الخدمة. وسيتم استخدام هذه المعلومات لتحسين أداء "مكتبة الفوترة" في Play وتقديم دعم أفضل للأخطاء.

إصدار 5.2.1 من Google Play Billing Library‏ (‎22/06/2023)

أصبح الإصدار 5.2.1 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

عليك تحديث Play Billing Library لتكون متوافقة مع Android 14.

الإصدار 5.2 من Google Play Billing Library‏ (‎06/04/2023)

أصبح الإصدار 5.2.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

الإصدار 5.1 من "مكتبة الفوترة في Google Play" (‎31/10/2022)

أصبح الإصدار 5.1.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

الإصدار 5.0 من Google Play Billing Library ‏ (‎11/05/2022)

أصبح الإصدار 5.0.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

  • طرحنا نموذجًا جديدًا للاشتراكات، بما في ذلك كيانات جديدة تسمح لك بإنشاء عروض متعددة لمنتج اشتراك واحد. لمزيد من المعلومات، يمكنك الاطّلاع على دليل نقل البيانات.
  • تمت إضافة BillingClient.queryProductDetailsAsync() لاستبدال BillingClient.querySkuDetailsAsync().
  • تمت إضافة طريقة setIsOfferPersonalized() لمتطلبات الإفصاح عن الأسعار المخصّصة في الاتحاد الأوروبي. لمزيد من المعلومات حول كيفية استخدام هذه الطريقة، اطّلِع على مقالة الإشارة إلى سعر مخصّص.
  • تمت إزالة queryPurchases()، التي تم إيقافها نهائيًا في السابق واستبدالها بالدالة queryPurchasesAsync التي تم تقديمها في الإصدار 4.0.0 من Google Play Billing Library.
  • تم إيقاف launchPriceChangeFlow نهائيًا وستتم إزالته في أحد الإصدارات القادمة. لمعرفة مزيد من المعلومات عن الخطوات البديلة، يُرجى الاطّلاع على مقالة بدء مسار تأكيد تغيير السعر.
  • تمت إزالة setVrPurchaseFlow()، الذي كان يُستخدَم سابقًا عند إنشاء مسار شراء. في الإصدارات السابقة، كانت هذه الطريقة تعيد توجيه المستخدم إلى إكمال عملية الشراء على جهاز Android. بعد إزالة هذه الطريقة، سيُكمل المستخدمون عملية الشراء من خلال مسار الشراء العادي.

إصدار 4.1 من Google Play Billing Library ‏ (‎23/02/2022)

أصبح الإصدار 4.1.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

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

الإصدار 4.0 من "مكتبة الفوترة في Google Play" (‎18/05/2021)

أصبح الإصدار 4.0.0 من Google Play Billing Library وإضافات Kotlin متوفرة الآن.

ملخص التغييرات

إصدار 3.0.3 من "مكتبة الفوترة في Google Play" (‎12‏/03‏/2021)

يتوفّر الآن الإصدار 3.0.3 من Google Play Billing Library وإضافة Kotlin وPlugin لـ Unity.

إصلاحات الأخطاء في Java وKotlin

  • إصلاح تسرب الذاكرة عند استدعاء endConnection()
  • حلّ مشكلة استخدام تطبيقات تتعلّق بوضع "بدء مهمة واحدة" لـ Google Play Billing Library سيتم بدء callback onPurchasesUpdated() عند استئناف تطبيق من مشغّل Android وكان مربّع حوار الفوترة مرئيًا قبل تعليقه.

إصلاحات أخطاء Unity

  • عليك التحديث إلى الإصدار 3.0.3 من Java لإصلاح تسرب الذاكرة وحلّ المشكلة التي تمنع عمليات الشراء عند استئناف تطبيق من مشغّل Android وكان مربّع حوار الفوترة مرئيًا قبل تعليقه.

إصدار Google Play Billing Library 3.0.2 (‎24/11/2020)

يتوفّر الآن الإصدار 3.0.2 من مكتبة Google Play Billing Library وإضافة Kotlin.

إصلاح الأخطاء

  • تم إصلاح خلل في إضافة Kotlin حيث يتعذّر تشغيل دالة coroutine مع ظهور الخطأ "تم استئناف المعالجة من قبل".
  • تم إصلاح الإحالات غير المحسَّنة عند استخدام إضافة Kotlin مع الإصدار 1.4 من مكتبة kotlinx.coroutines أو الإصدارات الأحدث.

إصدار 3.0.1 من مكتبة الفوترة في Google Play (‎30‏/09‏/2020)

يتوفّر الآن الإصدار 3.0.1 من مكتبة Google Play Billing Library وإضافة Kotlin.

إصلاح الأخطاء

  • تم إصلاح خطأ كان يؤدي إلى عدم استدعاء PurchasesUpdatedListener مع نتيجة الشراء في حال إغلاق التطبيق واستعادته أثناء عملية الفوترة.

الإصدار 3.0 من Google Play Billing Library (‎08-06-2020)

يتوفّر الآن الإصدار 3.0.0 من Google Play Billing Library وإضافة Kotlin ومكوّن Unity الإضافي.

ملخص التغييرات

  • تمت إزالة إمكانية استخدام رموز التخزين التعريفية للمكافآت.
  • أزلت المَعلمتَين ChildDirected وUnderAgeOfConsent.
  • تمت إزالة طرق الحمولة للمطوّرين التي تم إيقافها نهائيًا.
  • تمّت إزالة الطريقتَين BillingFlowParams.setAccountId() وBillingFlowParams.setDeveloperId() اللتين تم إيقافهما نهائيًا.
  • تمّت إزالة الطريقتَين BillingFlowParams.setOldSkus(String oldSku) وBillingFlowParams.addOldSku(String oldSku) اللتين تم إيقافهما نهائيًا.
  • تمت إضافة تعليقات توضيحية حول إمكانية تحديد قيمة صفرية للسمة.

إصلاح الأخطاء

  • يعرض الآن SkuDetails.getIntroductoryPriceCycles() int بدلاً من String.
  • تم إصلاح خلل كان يؤدي إلى اعتبار عملية الفوترة أنّها تحتوي على مَعلمات إضافية حتى في حال عدم ضبط أي مَعلمات إضافية.

إصدار 2.2.1 من مكتبة الفوترة في Google Play‏ (‎20/05/2020)

يتوفّر الآن الإصدار 2.2.1 من مكتبة Google Play Billing.

إصلاح الأخطاء

  • تم تعديل الإصدار التلقائي من مكتبة Java Play Billing التي تعتمد عليها إضافات Kotlin.

إصدار Google Play Billing Library 2.2.0 وتوافقه مع Unity (‎23/03/2020)

يقدّم الإصدار 2.2.0 من "الفوترة في Google Play" وظائف تساعد المطوّرين في التأكّد من أنّ عمليات الشراء منسوبة إلى المستخدم الصحيح. وتؤدي هذه التغييرات إلى عدم الحاجة إلى إنشاء حلول مخصّصة استنادًا إلى الحمولة البرمجية للمطوّر. وكجزء من هذا التعديل، تم إيقاف وظائف الحمولة للمطوّرين نهائيًا، وستتم إزالتها في إصدار مستقبلي. لمزيد من المعلومات، بما في ذلك البدائل المقترَحة، يُرجى الاطّلاع على حمولة المطوّر.

Google Play Billing Billing Library 2 for Unity

بالإضافة إلى إصدارَي Java وKotlin الحاليَين من Google Play Billing Library 2، طرحنا إصدارًا من المكتبة لاستخدامه مع Unity. يمكن لمطوّري الألعاب الذين يستخدمون واجهة برمجة التطبيقات Unity In-App Purchase API الترقية الآن للاستفادة من جميع ميزات Google Play Billing Library 2 وتسهيل الترقيات اللاحقة إلى الإصدارات المستقبلية من Google Play Billing Library.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة استخدام خدمة "الفوترة في Google Play" مع Unity.

ملخص التغييرات

إصدار 2.1.0 من Google Play Billing Library وإصدار 2.1.0 من Kotlin Extension (10‏ كانون الأول/ديسمبر 2019)

يتوفّر الآن الإصدار 2.1.0 من مكتبة Google Play Billing وإضافة Kotlin الجديدة. توفّر إضافة Kotlin في مكتبة الفوترة على Play بدائل مألوفة لواجهات برمجة التطبيقات لاستخدامها مع Kotlin، وتتميز بأمان أفضل للقيم الفارغة و عمليات التشغيل المتعدّدة. للاطّلاع على أمثلة على الرموز البرمجية، يمكنك الاطّلاع على مقالة استخدام Google Play Billing Library.

يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

  • في BillingFlowParams، تم إيقاف setOldSku(String oldSku) نهائيًا واستبداله بأحد الخيارَين التاليَين: setOldSku(String oldSku, String purchaseToken)، وذلك لإزالة الغموض عندما تمتلك حسابات متعدّدة على الجهاز رقم تعريف التخزين التعريفي نفسه.

الإصدار 2.0.3 من مكتبة الفوترة في Google Play (‎05-08-2019)

يتوفّر الآن الإصدار 2.0.3 من مكتبة Google Play Billing.

إصلاح الأخطاء

  • تم إصلاح خطأ كان يؤدي إلى تعذُّر إكمال عملية querySkuDetailsAsync() في بعض الأحيان مع ظهور الرمز DEVELOPER_ERROR بدلاً من عرض نتيجة ناجحة.

إصدار 2.0.2 من Google Play Billing Library (‎08-07-2019)

يتوفّر الآن الإصدار 2.0.2 من مكتبة Google Play Billing. يحتوي هذا الإصدار على تعديلات على المستندات المرجعية ولا يغيّر وظائف المكتبة.

إصدار 2.0.1 من Google Play Billing Library (‎06-06-2019)

يتوفّر الآن الإصدار 2.0.1 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

إصلاح الأخطاء

  • تم إصلاح خطأ كان يؤدي إلى عرض رسائل تصحيح الأخطاء على شكل null في بعض الحالات.
  • تم إصلاح مشكلة محتملة في تسرب الذاكرة.

الإصدار 2.0 من "مكتبة الفوترة في Google Play" (07‏ أيار (مايو) 2019)

يتوفّر الآن الإصدار 2.0 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

يجب إعلامنا باستلام رسوم الاشتراك خلال ثلاثة أيام.

يتيح Google Play شراء المنتجات من داخل تطبيقك (داخل التطبيق) أو خارج تطبيقك (خارج التطبيق). لكي يضمن Google Play تقديم تجربة شراء متّسقة بغض النظر عن مكان شراء العميل لمنتجاتك، يجب الردّ على جميع عمليات الشراء التي يتم تلقّيها من خلال Google Play Billing Library في أقرب وقت ممكن بعد منح العميل الإذن بالوصول إلى المحتوى. إذا لم يتم الإقرار بإتمام عملية شراء في غضون ثلاثة أيام، سيتم تلقائيًا ردّ الأموال إلى المستخدم، وسيلغي Google Play عملية الشراء. بالنسبة إلى المعاملات التي في انتظار المراجعة (ميزة جديدة في الإصدار 2.0)، تبدأ مهلة الأيام الثلاثة عندما تنتقل عملية الشراء إلى الحالة PURCHASED ولا تنطبق عندما تكون عملية الشراء في الحالة PENDING.

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

يتضمّن عنصر Purchase الآن isAcknowledged() طريقة تشير إلى ما إذا تمّ الإقرار بعملية شراء. بالإضافة إلى ذلك، تتضمّن واجهة برمجة التطبيقات Google Play Developer API قيمًا منطقية للإقرار لكل من Purchases.products وPurchases.subscriptions. قبل الموافقة على عملية شراء، احرص على استخدام هذه الطرق لتحديد ما إذا كان قد تم الموافقة على عملية الشراء من قبل.

يمكنك الموافقة على عملية شراء باستخدام إحدى الطريقتَين التاليتَين:

  • بالنسبة إلى المنتجات الاستهلاكية، استخدِم consumeAsync() المتوفّرة في واجهة برمجة تطبيقات العميل.
  • بالنسبة إلى المنتجات التي لا يتم استهلاكها، استخدِم acknowledgePurchase() المتوفّرة في واجهة برمجة تطبيقات العميل.
  • تتوفّر أيضًا طريقة acknowledge() جديدة في Server API.

تمت إزالة BillingFlowParams.setSku()

تمت إزالة الطريقة BillingFlowParams#setSku() التي تم إيقافها نهائيًا في الإصدار السابق في هذا الإصدار. قبل عرض المنتجات في مسار الشراء، يجب الآن استدعاء BillingClient.querySkuDetailsAsync()، مع تمرير العنصر resulting SkuDetails إلى BillingFlowParams.Builder.setSkuDetails().

للاطّلاع على أمثلة على الرموز البرمجية، يمكنك الاطّلاع على مقالة استخدام Google Play Billing Library.

تتوفّر حِزم بيانات المطوّرين

يضيف الإصدار 2.0 من مكتبة الفوترة في Google Play إمكانية استخدام developer payload، وهي سلاسل عشوائية يمكن إرفاقها بعمليات الشراء. يمكنك إرفاق مَعلمة "حمولة المطوّر" بعملية شراء، ولكن فقط عند إقرار عملية الشراء أو استخدامها. يختلف ذلك عن الحمولة المخصّصة للمطوّر في AIDL، حيث يمكن تحديد الحِمولة عند بدء مسار الشراء. بما أنّه يمكن الآن بدء عمليات الشراء من خارج تطبيقك، يضمن لك هذا التغيير إمكانية إضافة حمولة إلى عمليات الشراء في أي وقت.

للوصول إلى الحمولة في المكتبة الجديدة، تتضمّن عناصر Purchase الآن getDeveloperPayload() طريقة.

العروض المتسقة

عند تقديم رمز تخزين تعريفي بسعر مخفَّض، يعرض Google Play الآن السعر الأصلي لرمز التخزين التعريفي حتى تتمكّن من إظهار المستخدمين أنّهم يحصلون على خصم.

يحتوي SkuDetails على طريقتَين جديدتَين لاسترداد سعر رمز التخزين التعريفي الأصلي:

  • ‫getOriginalPriceAmountMicros(): تعرض هذه السمة السعر الأصلي غير المنسَّق لرقم التخزين التعريفي قبل الخصم.
  • ‫getOriginalPrice(): تعرض السعر الأصلي مع تنسيق إضافي للعملة.

المعاملات المعلّقة:

باستخدام الإصدار 2.0 من مكتبة "الفوترة في Google Play"، يجب أن تتيح عمليات الشراء التي تتطلّب اتّخاذ إجراء إضافي قبل منح الإذن بها. على سبيل المثال، قد يختار المستخدم شراء منتجك داخل التطبيق من متجر حقيقي باستخدام النقود. وهذا يعني أنّه تم إكمال المعاملة خارج تطبيقك. في هذا السيناريو، يجب منح الإذن فقط بعد أن يكمل المستخدم المعاملة.

لتفعيل عمليات الشراء المعلّقة، يمكنك الاتصال بالخدمة enablePendingPurchases() كجزء من عملية إعداد تطبيقك.

استخدِم Purchase.getPurchaseState() لتحديد ما إذا كانت حالة الشراء هي PURCHASED أو PENDING. يُرجى العلم أنّه ينبغي منح الإذن فقط عندما تكون الحالة هي PURCHASED. عليك التحقّق من آخر المعلومات عن حالة Purchase باتّباع الخطوات التالية:

  1. عند بدء تطبيقك، يمكنك الاتصال بالخدمة BillingClient.queryPurchases() لاسترداد قائمة المنتجات غير المستخدَمة المرتبطة بالمستخدم.
  2. استخدِم Purchase.getPurchaseState() مع كل عنصر Purchase يتم إرجاعه.
  3. نفِّذ الطريقة onPurchasesUpdated() للاستجابة للتغييرات في عناصر Purchase.

بالإضافة إلى ذلك، تتضمّن Google Play Developer API حالة PENDING لـ Purchases.products. لا تتوفّر المعاملات غير المكتملة لعمليات شراء الاشتراكات.

يقدّم هذا الإصدار أيضًا نوعًا جديدًا من الإشعارات في الوقت الفعلي للمطوّرين، وهو OneTimeProductNotification. يحتوي نوع الإشعار هذا على رسالة واحدة تكون قيمتها إما ONE_TIME_PRODUCT_PURCHASED أو ONE_TIME_PRODUCT_CANCELED. لا يتم إرسال هذا النوع من الإشعارات إلا لعمليات الشراء المرتبطة بطرق الدفع التي تستغرق وقتًا أطول، مثل الدفع نقدًا.

عند الموافقة على عمليات الشراء المعلّقة، احرص على الموافقة فقط عندما تكون حالة الشراء هي PURCHASED وليس PENDING.

التغييرات في واجهة برمجة التطبيقات

يتضمّن الإصدار 2.0 من مكتبة Google Play Billing عدة تغييرات على واجهة برمجة التطبيقات لسماح التطبيقات باستخدام ميزات جديدة وتوضيح وظائفها الحالية.

consumeAsync

يقبل consumeAsync() الآن ConsumeParams بدلاً من purchaseToken. يحتوي ConsumeParams على purchaseToken بالإضافة إلى حمولة مطوّر اختيارية.

تمت إزالة الإصدار السابق من consumeAsync() في هذا الإصدار.

queryPurchaseHistoryAsync

لتقليل الالتباس، يعرض الرمز queryPurchaseHistoryAsync() الآن عنصرًا PurchaseHistoryRecord بدلاً من عنصر Purchase. عنصر PurchaseHistoryRecord هو نفسه عنصر Purchase، باستثناء أنّه لا يعرض سوى القيم التي يعرضها queryPurchaseHistoryAsync() ولا يحتوي على الحقول autoRenewing و orderId وpackageName. يُرجى العِلم أنّه لم يحدث أي تغيير في البيانات المعروضة، إذ يعرض الإجراءqueryPurchaseHistoryAsync() البيانات نفسها التي كانت معروضة في السابق.

قيم الإرجاع في BillingResult

واجهات برمجة التطبيقات التي كانت تُرجع سابقًا قيمة عددية BillingResponse تُرجع الآن عنصرًا BillingResult. يحتوي BillingResult على العدد الصحيح BillingResponse بالإضافة إلى سلسلة debugging التي يمكنك استخدامها لتشخيص الأخطاء. تستخدم سلسلة تصحيح الأخطاء لغة en-US ولا يُقصد عرضها للمستخدمين النهائيين.

إصلاح الأخطاء

إصدار 1.2.2 من "مكتبة الفوترة في Google Play" (07‏/03‏/2019)

يتوفّر الآن الإصدار 1.2.2 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

إصلاح الأخطاء

  • تم إصلاح مشكلة في سلسلة المحادثات ظهرت في الإصدار 1.2.1. لم تعُد المكالمات التي تعمل في الخلفية تحظر سلسلة التعليمات الرئيسية.

تغييرات أخرى

  • على الرغم من أنّه لا يزال يُنصح باستخدام سلسلة المهام الرئيسية، يمكنك الآن إنشاء مثيل لمكتبة Google Play Billing Library من سلسلة مهام في الخلفية.
  • تم نقل عملية الإنشاء بالكامل إلى سلسلة المهام في الخلفية لتقليل احتمالية حدوث أخطاء ANR.

إصدار 1.2.1 من "مكتبة الفوترة في Play" (‎04-03-2019)

يتوفّر الآن الإصدار 1.2.1 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

التغييرات الرئيسية

تغييرات أخرى

  • تمت إضافة وظائف إنشاء عامة لكل من PurchasesResult وSkuDetailsResult لتسهيل الاختبار.
  • يمكن أن تستخدم عناصر SkuDetails طريقة جديدة، وهي getOriginalJson().
  • تتم الآن معالجة جميع طلبات خدمة AIDL من خلال سلاسل مهام الخلفية.

إصلاح الأخطاء

  • لم تعُد أدوات الاستماع إلى عمليات الاستدعاء التي لا تحتوي على قيمة تمرّر إلى واجهات برمجة التطبيقات المتاحة للجميع.

الإصدار 1.2 من مكتبة الفوترة في Google Play (‎18-10-2018)

يتوفّر الآن الإصدار 1.2 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

  • تم ترخيص واجهة برمجة التطبيقات Google Play Billing Library الآن بموجب اتفاقية ترخيص حزمة تطوير البرامج لنظام Android.
  • تمت إضافة واجهة برمجة التطبيقات launchPriceChangeConfirmationFlow التي تطلب من المستخدمين مراجعة تغيير في انتظار المراجعة لسعر الاشتراك.
  • تمت إضافة وضع تقسيم جديد، وهو DEFERRED، عند ترقية اشتراك مستخدم أو خفضه.
  • في فئة BillingFlowParams، استُبدِل setSku() بـ setSkuDetails().
  • إصلاح أخطاء بسيطة وتحسينات على الرموز البرمجية

تأكيد تغيير السعر

يمكنك الآن تغيير سعر اشتراك في Google Play Console وطلب مراجعة المستخدمين للسعر الجديد وقبوله عند دخولهم إلى تطبيقك.

لاستخدام واجهة برمجة التطبيقات هذه، أنشئ عنصرًا من النوع PriceChangeFlowParams باستخدام skuDetails لمنتج الاشتراك، ثم استخدِم launchPriceChangeConfirmationFlow(). نفِّذ الإجراء PriceChangeConfirmationListener للتعامل مع النتيجة عند انتهاء عملية تأكيد تغيير السعر، كما هو موضّح في مقتطف الرمز البرمجي التالي:

Kotlin

val priceChangeFlowParams = PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build()

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        object : PriceChangeConfirmationListener() {
            override fun onPriceChangeConfirmationResult(responseCode: Int) {
                // Handle the result.
            }
        })

Java

PriceChangeFlowParams priceChangeFlowParams =
        PriceChangeFlowParams.newBuilder()
    .setSkuDetails(skuDetailsOfThePriceChangedSubscription)
    .build();

billingClient.launchPriceChangeConfirmationFlow(activity,
        priceChangeFlowParams,
        new PriceChangeConfirmationListener() {
            @Override
            public void onPriceChangeConfirmationResult(int responseCode) {
                // Handle the result.
            }
        });

تعرِض عملية تأكيد تغيير السعر مربّع حوار يحتوي على معلومات تتعلّق بالسعر الجديد، وتطلب من المستخدمين قبول السعر الجديد. تُعرِض هذه العملية رمز استجابة من النوع BillingClient.BillingResponse.

وضع تقسيم التكلفة الجديد

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

طريقة جديدة لضبط تفاصيل رمز التخزين التعريفي

في فئة BillingFlowParams، تم إيقاف الطريقة setSku() نهائيًا. يهدف هذا التغيير إلى تحسين عملية الفوترة في Google Play.

عند إنشاء مثيل جديد من BillingFlowParams في العميل لنظام الفوترة داخل التطبيق، ننصحك بالعمل مع عنصر JSON مباشرةً باستخدام setSkuDetails() بدلاً من ذلك، كما هو موضّح في مقتطف الرمز البرمجي التالي:

في فئة BillingFlowParams Builder، تم إيقاف استخدام الطريقة setSku(). بدلاً من ذلك، استخدِم الطريقة setSkuDetails()، كما هو موضّح في مقتطف الرمز التالي. يأتي العنصر الذي تم تمريره إلى عنصر setSkuDetails() من الطريقة querySkuDetailsAsync().

Kotlin

private lateinit var mBillingClient: BillingClient
private val mSkuDetailsMap = HashMap<String, SkuDetails>()

private fun querySkuDetails() {
    val skuDetailsParamsBuilder = SkuDetailsParams.newBuilder()
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build()
    ) { responseCode, skuDetailsList ->
        if (responseCode == 0) {
            for (skuDetails in skuDetailsList) {
                mSkuDetailsMap[skuDetails.sku] = skuDetails
            }
        }
    }
}

private fun startPurchase(skuId: String) {
    val billingFlowParams = BillingFlowParams.newBuilder()
    .setSkuDetails(mSkuDetailsMap[skuId])
    .build()
}

Java

private BillingClient mBillingClient;
private Map<String, SkuDetails> mSkuDetailsMap = new HashMap<>();

private void querySkuDetails() {
    SkuDetailsParams.Builder skuDetailsParamsBuilder
            = SkuDetailsParams.newBuilder();
    mBillingClient.querySkuDetailsAsync(skuDetailsParamsBuilder.build(),
            new SkuDetailsResponseListener() {
                @Override
                public void onSkuDetailsResponse(int responseCode,
                        List<SkuDetails> skuDetailsList) {
                    if (responseCode == 0) {
                        for (SkuDetails skuDetails : skuDetailsList) {
                            mSkuDetailsMap.put(skuDetails.getSku(), skuDetails);
                        }
                    }
                }
            });
}

private void startPurchase(String skuId) {
    BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
            .setSkuDetails(mSkuDetailsMap.get(skuId))
            .build();
}

إصدار 1.1 من "مكتبة الفوترة في Play" (07‏-05‏-2018)

يتوفّر الآن الإصدار 1.1 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

ملخص التغييرات

  • تمت إضافة إمكانية تحديد وضع تقسيم الفاتورة في BillingFlowParams عند ترقية اشتراك حالي أو خفض فئته.
  • لم يعُد الخيار المنطقي replaceSkusProration في BillingFlowParams متاحًا. استخدِم replaceSkusProrationMode بدلاً من ذلك.
  • launchBillingFlow() يؤدي الآن إلى إعادة الاتصال للاستجابات التي تعذّر إرسالها.

تغييرات السلوك

يتضمّن الإصدار 1.1 من مكتبة Google Play Billing السلوك التالي التغييرات.

يمكن للمطوّرين ضبط replaceSkusProrationMode في فئة BillingFlowParams.

يوفّر ProrationMode مزيدًا من التفاصيل حول نوع التقسيم عند ترقية اشتراك أحد المستخدِمين أو الرجوع إلى إصدار سابق منه.

Kotlin

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build()

Java

BillingFlowParams.newBuilder()
    .setSku(skuId)
    .setType(billingType)
    .setOldSku(oldSku)
    .setReplaceSkusProrationMode(replaceSkusProrationMode)
    .build();

يتيح Google Play حاليًا أوضاع تقسيم الاشتراكات التالية:

IMMEDIATE_WITH_TIME_PRORATION يسري الاستبدال على الفور، وسيتم تقسيم وقت انتهاء الصلاحية الجديد بالتساوي وسيتم ردّ الأموال إلى المستخدم أو تحصيلها منه. وهذا هو السلوك التلقائي الحالي.
IMMEDIATE_AND_CHARGE_PRORATED_PRICE يسري الاستبدال على الفور، وتبقى دورة الفوترة كما هي. سيتم تحصيل سعر الفترة المتبقية.

ملاحظة: لا يتوفّر هذا الخيار إلّا لترقية الاشتراك.
IMMEDIATE_WITHOUT_PRORATION يسري الاستبدال على الفور، وسيتم تحصيل السعر الجديد عند تكرار الاشتراك في المرة التالية. تبقى دورة الفوترة كما هي.

لم يعُد تطبيق replaceSkusProration متوافقًا مع فئة BillingFlowParams

في السابق، كان بإمكان المطوّرين ضبط علامة منطقية لفرض مبلغ مُقسَّم على أساس النسبة المئوية لطلب ترقية الاشتراك. بما أنّنا نوفّر ProrationMode الذي يحتوي على تعليمات proration أكثر تفصيلاً، لم تعُد هذه العلامة المنطقية متاحة.

يُشغِّل launchBillingFlow() الآن طلب إعادة الاتصال للاستجابات التي تعذّر إرسالها.

ستشغِّل "مكتبة الفوترة" دائمًا دالة الاستدعاء PurhcasesUpdatedListener وستُرجع BillingResponse بشكل غير متزامن. يتم أيضًا الاحتفاظ بالقيمة المعروضة المتزامنة BillingResponse.

إصلاح الأخطاء

  • الخروج بشكل صحيح في وقت مبكر من الطرق غير المتزامنة عند انقطاع الاتصال بالخدمة
  • Builder لم تعُد عناصر param تُغيّر الكائنات المُنشأة.
  • المشكلة 68087141: launchBillingFlow() يؤدي الآن إلى إعادة الاتصال في حال تعذُّر تلقّي ردود.

إصدار 1.0 من "مكتبة الفوترة في Google Play" (‎19-09-2017، الإشعار)

يتوفّر الآن الإصدار 1.0 من مكتبة Google Play Billing. يتضمّن هذا الإصدار التغييرات التالية.

التغييرات المهمة

  • إذن الفوترة المضمّن في بيان المكتبة لم يعُد من الضروري إضافة إذن com.android.vending.BILLING داخل ملف بيان Android.
  • تمّت إضافة أداة إنشاء جديدة إلى صف BillingClient.Builder.
  • تمّ تقديم نمط المُنشئ لفئة SkuDetailsParams للاستخدام في طُرق طلب البحث عن رموز التخزين التعريفية.
  • تم تعديل العديد من طرق واجهة برمجة التطبيقات لتحقيق الاتساق (أسماء وسيطات الإرجاع ورتبها نفسها).

تغييرات السلوك

يتضمّن الإصدار 1.0 من مكتبة "الفوترة في Google Play" التغيُّرات التالية في السلوك.

فئة BillingClient.Builder

تم الآن إعداد BillingClient.Builder من خلال نموذج newBuilder:

Kotlin

billingClient = BillingClient.newBuilder(context).setListener(this).build()

Java

billingClient = BillingClient.newBuilder(context).setListener(this).build();

يتم الآن استدعاء طريقة launchBillingFlow باستخدام فئة BillingFlowParams

لبدء عملية الفوترة لعملية شراء أو اشتراك، تتلقّى الطريقة launchBillingFlow() مثيلًا من BillingFlowParams تم إعداده باستخدام مَعلمات خاصة بالطلب:

Kotlin

BillingFlowParams.newBuilder().setSku(skuId)
        .setType(billingType)
        .setOldSku(oldSku)
        .build()

// Then, use the BillingFlowParams to start the purchase flow
val responseCode = billingClient.launchBillingFlow(builder.build())

Java

BillingFlowParams.newBuilder().setSku(skuId)
                              .setType(billingType)
                              .setOldSku(oldSku)
                              .build();

// Then, use the BillingFlowParams to start the purchase flow
int responseCode = billingClient.launchBillingFlow(builder.build());

طريقة جديدة لطلب المنتجات المتوفّرة

تم تضمين وسيطات طريقتَي queryPurchaseHistoryAsync() وquerySkuDetailsAsync() في نمط Builder:

Kotlin

val params = SkuDetailsParams.newBuilder()
params.setSkusList(skuList)
        .setType(itemType)
billingClient.querySkuDetailsAsync(params.build(), object : SkuDetailsResponseListener() {
    ...
})

Java

SkuDetailsParams.Builder params = SkuDetailsParams.newBuilder();
params.setSkusList(skuList)
        .setType(itemType);
billingClient.querySkuDetailsAsync(params.build(), new SkuDetailsResponseListener() {...})

يتم الآن عرض النتيجة من خلال رمز النتيجة وقائمة بعناصر SkuDetails بدلاً من فئة الغلاف السابقة، وذلك لتسهيل الأمر عليك وضمان الاتساق في واجهة برمجة التطبيقات:

Kotlin

fun onSkuDetailsResponse(@BillingResponse responseCode: Int, skuDetailsList: List<SkuDetails>)

Java

public void onSkuDetailsResponse(@BillingResponse int responseCode, List<SkuDetails> skuDetailsList)

تم تغيير ترتيب المَعلمات في طريقة onConsumeResponse()

تم تغيير ترتيب وسيطات onConsumeResponse من واجهة ConsumeResponseListener لتكون متسقة في واجهة برمجة التطبيقات:

Kotlin

fun onConsumeResponse(@BillingResponse responseCode: Int, outToken: String)

Java

public void onConsumeResponse(@BillingResponse int responseCode, String outToken)

عنصر PurchaseResult غير المُغلف

تم إزالة PurchaseResult ليكون متوافقًا مع واجهة برمجة التطبيقات:

Kotlin

fun onPurchaseHistoryResponse(@BillingResponse responseCode: Int, purchasesList: List<Purchase>)

Java

void onPurchaseHistoryResponse(@BillingResponse int responseCode, List<Purchase> purchasesList)

إصلاح الأخطاء

إصدار "الإصدار التجريبي للمطوّرين" 1 (12 حزيران/يونيو 2017، الإشعار)

إطلاق ميزة "معاينة المطوّر" بهدف تبسيط عملية التطوير في ما يتعلق بالفوترة، مما يتيح للمطوّرين تركيز جهودهم على تنفيذ منطق خاص بتطبيق Android، مثل بنية التطبيق وبنية التنقّل

تتضمّن المكتبة العديد من الفئات والميزات المفيدة التي يمكنك استخدامها عند دمج تطبيقات Android مع Google Play Billing API. توفّر المكتبة أيضًا طبقة تجريدية فوق خدمة لغة تعريف واجهة Android (AIDL)، ما يسهّل على المطوّرين تحديد الواجهة بين التطبيق وGoogle Play Billing API.