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

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

إصدار 8.0.0 من Google Play Billing Library‏ (‎30/06/2025)

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

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

  • سيتم الآن الإشارة إلى العناصر داخل التطبيق باسم المنتجات التي يتم تحصيل سعرها مرة واحدة.

  • خيارات وعروض متعددة للشراء للمنتجات التي يتم تحصيل سعرها مرة واحدة

    يمكنك الآن الحصول على خيارات وعروض شراء متعددة لمنتجاتك التي يتم شراؤها لمرة واحدة. يمنحك ذلك مرونة في طريقة بيع منتجاتك ويسهّل إدارتها.

  • تم تحسين طريقة queryProductDetailsAsync().

    قبل الإصدار 8.0.0 من PBL، لم تكن طريقة queryProductDetailsAsync() تُعيد المنتجات التي تعذّر جلبها. وقد يرجع ذلك إلى أسباب مثل عدم العثور على المنتج أو عدم توفّر عروض للمستخدم. في الإصدار PBL 8.0.0، يتم عرض المنتجات التي لم يتم استرجاعها مع رمز حالة جديد على مستوى المنتج يقدّم معلومات عن المنتجات التي لم يتم استرجاعها. يُرجى العِلم أنّه حدث تغيير في توقيع ProductDetailsResponseListener.onProductDetailsResponse() مما يتطلب إجراء تغييرات في تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على معالجة النتيجة.

  • إعادة الاتصال بالخدمة تلقائيًا

    تتيح المَعلمة الجديدة BillingClient.Builder.enableAutoServiceReconnection() لصانع التطبيقات تفعيل إعادة الاتصال بالخدمة تلقائيًا، ما يؤدي بدوره إلى تبسيط إدارة الاتصال من خلال إعادة ربطه بـ "خدمة الفوترة في Play" تلقائيًا، ما يغني المطوّرين عن استدعاء startConnection() يدويًا في حال انقطاع الاتصال بالخدمة. لمزيد من المعلومات، يُرجى الاطّلاع على إعادة الاتصال تلقائيًا.

  • رموز الاستجابة الفرعية لطريقة launchBillingFlow()

    سيتضمّن الآن BillingResult الذي تم إرجاعه من launchBillingFlow() حقل رمز استجابة فرعي. لن تتم تعبئة هذا الحقل إلا في بعض الحالات لتقديم سبب أكثر تحديدًا للتعذُّر. في الإصدار 8.0.0 من تنسيق PBL، يتم عرض الرمز الفرعي PAYMENT_DECLINED_DUE_TO_INSUFFICIENT_FUNDS في الحالة التي يكون فيها رصيد المستخدم أقل من سعر المنتج الذي يحاول شراءه.

  • تمت إزالة طريقة queryPurchaseHistory().

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

  • تمت إزالة طريقة querySkuDetailsAsync().

    تمّت إزالة طريقة querySkuDetailsAsync() التي تم وضع علامة عليها سابقًا على أنّها متوقّفة نهائيًا. يجب استخدام queryProductDetailsAsync بدلاً من ذلك.

  • تمت إزالة طريقة BillingClient.Builder.enablePendingPurchases().

    تمّت إزالة طريقة enablePendingPurchases() التي لا تتضمّن أيّ معلَمات والتي تم وضع علامة عليها سابقًا بأنّها متوقّفة نهائيًا. يجب استخدام enablePendingPurchases(PendingPurchaseParams params) بدلاً من ذلك. يُرجى العِلم أنّ enablePendingPurchases() المتوقّفة نهائيًا لها وظيفة مماثلة لenablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()).

  • تمت إزالة طريقة queryPurchasesAsync() التي تمّ تحميلها بشكل زائد والتي تأخذ skuType.

    تمّت إزالة طريقة queryPurchasesAsync(String skuType, PurchasesResponseListener listener) التي تمّ وضع علامة عليها في السابق على أنّها متوقفة نهائيًا. بدلاً من ذلك، استخدِم queryPurchasesAsync(QueryPurchasesParams queryPurchasesParams, PurchasesResponseListener listener).

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

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

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

  • تم إصلاح خطأ في الإصدار 7.1.0 من "مكتبة الفوترة في Google Play" يتعلق برموز استجابة testing BillingResult.

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

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

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

  • أمان مُحسَّن للخيوط المتعلّقة بحالة الاتصال وإدارته
  • تمّت إضافة تغييرات جزئية لاختبار رموز الاستجابة [BillingResult][billing-result] التي تمّ إصدارها بالكامل في الإصدار 7.1.1 من مكتبة Play Billing Library. لاختبار عملية الدمج باستخدام هذه الميزة، عليك الترقية إلى الإصدار 7.1.1 من مكتبة الفوترة في Play. هناك خطأ سيؤثر فقط في التطبيقات التي تم فيها تفعيل ميزة [billing overrides testing enabled][enable-billing-overrides-testing] ولن يؤثر في الاستخدام العادي. لمزيد من المعلومات، يُرجى الاطّلاع على اختبار BillingResult رموز الاستجابة. [billing-result]:‏ ‎/reference/com/android/billingclient/api/BillingResult [enable-billing-overrides-testing]:‏ ‎/google/play/billing/test-response-codes#enable-billing-overrides-testing

إصدار 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 متوفرة الآن.

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

  • تمت إضافة رمز BillingClient.queryPurchasesAsync() لاستبدال رمز BillingClient.queryPurchases() الذي ستتم إزالته في إصدار مستقبلي.

  • تمت إضافة وضع استبدال اشتراك جديد IMMEDIATE_AND_CHARGE_FULL_PRICE.

  • تمت إضافة BillingClient.getConnectionState() طريقة لاسترداد حالة الاتصال بـ "مكتبة الفوترة في Play".

  • تم تعديل Javadoc وطريقة التنفيذ للإشارة إلى سلسلة المحادثات التي يمكن استدعاء طريقة فيها ونتائج سلسلة المحادثات التي يتم نشرها.

  • تمت إضافة BillingFlowParams.Builder.setSubscriptionUpdateParams() كطريقة جديدة لبدء تعديلات الاشتراك. يحلّ هذا الرمز محلّ BillingFlowParams#getReplaceSkusProrationMode، BillingFlowParams#getOldSkuPurchaseToken، BillingFlowParams#getOldSku، BillingFlowParams.Builder#setReplaceSkusProrationMode، BillingFlowParams.Builder#setOldSku التي تمت إزالتها.

  • تمت إضافة Purchase.getQuantity() و PurchaseHistoryRecord.getQuantity().

  • تمت إضافة Purchase#getSkus() و PurchaseHistoryRecord#getSkus(). وهذه العناصر تحلّ محل Purchase#getSku وPurchaseHistoryRecord#getSku اللذَين تمّت إزالتهما.

  • تمت إزالة BillingFlowParams#getSku وBillingFlowParams#getSkuDetails و BillingFlowParams#getSkuType.

إصدار 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 حيث يتعذّر تشغيل دالة معالجة المهام المتعدّدة في الخلفية مع ظهور الخطأ "تم استئناف المعالجة من قبل".
  • تم إصلاح الإحالات غير المحسَّنة عند استخدام إضافة 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 الترقية الآن للاستفادة من جميع ميزات الإصدار 2 من Google Play Billing Library وتسهيل الترقيات التالية إلى الإصدارات المستقبلية من Google Play Billing Library.

لمزيد من المعلومات، يُرجى الاطّلاع على مقالة استخدام خدمة "الفوترة في Google Play" مع IDE 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.

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

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

  • في الإصدار 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.

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

يضيف الإصدار 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، الذي يحتوي على تعليمات أكثر تفصيلاً لتوزيع التكلفة، لم يعُد استخدام هذا العلامة المنطقية متاحًا.

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

ستشغِّل "مكتبة الفوترة" دائمًا دالّة callback الخاصة بحالة 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.