يتضمّن هذا الموضوع ملاحظات إصدار Google Play Billing Library.
الإصدار 6.2.0 من Google Play Billing Library (06/03/2024)
يتوفّر الآن الإصدار 6.2.0 من Google Play Billing Library وإضافات Kotlin.
ملخص التغييرات
- تمت إضافة واجهات برمجة تطبيقات لإتاحة العروض الخارجية.
- تمت إضافة
BillingClient.Builder.enableExternalOffer()
لإتاحة إمكانية تقديم عروض خارجية. - تمت إضافة
BillingClient.isExternalOfferAvailableAsync()
للتحقق من مدى توفّر إمكانية تقديم وظائف عروض خارجية. - تمت إضافة
BillingClient.showExternalOfferInformationDialog()
لعرض مربّع حوار المعلومات للمستخدمين قبل توجيه المستخدمين خارج التطبيق. - تمت إضافة
BillingClient.createExternalOfferReportingDetailsAsync()
لإنشاء حمولة مطلوبة للإبلاغ عن المعاملات التي تمت من خلال عروض خارجية.
- تمت إضافة
الإصدار 6.1.0 من Google Play Billing Library (14/11/2023)
يتوفّر الآن الإصدار 6.1.0 من Google Play Billing Library وإضافات Kotlin.
ملخص التغييرات
- تمت إضافة واجهات برمجة التطبيقات لإتاحة نظام الفوترة البديل فقط (أي بدون خيار المستخدم)
- تمت إضافة
BillingClient.Builder.enableAlternativeBillingOnly()
لتفعيل إمكانية توفير نظام فوترة بديل فقط. - تمت إضافة
BillingClient.isAlternativeBillingOnlyAvailableAsync()
للتحقق من مدى توفّر خيار نظام فوترة بديل فقط. - تمت إضافة
BillingClient.showAlternativeBillingOnlyInformationDialog()
لعرض مربّع حوار المعلومات لإعلام المستخدمين عند استخدام نظام الفوترة البديل فقط. - تمت إضافة
BillingClient.createAlternativeBillingOnlyReportingDetailsAsync()
لإنشاء حمولة مطلوبة لإعداد تقارير عن المعاملات التي تتم من خلال نظام الفوترة البديل فقط.
- تمت إضافة
- تم تحديث واجهات برمجة التطبيقات لميزة الفوترة حسب اختيار المستخدم
- تمت إضافة
UserChoiceBillingListener
لاستبدال Alternative BillingListener الذي تم وضع علامة عليه بأنّه متوقّف نهائيًا. - تمت إضافة
UserChoiceDetails
لاستبدالAlternativeChoiceDetails
الذي تم وضع علامة عليه بأنّه متوقّف نهائيًا. - تمت إضافة
BillingClient.Builder.enableUserChoiceBilling()
لاستبدالBillingClient.Builder.enableAlternativeBilling()
الذي تم وضع علامة عليه بأنّه متوقّف نهائيًا.
- تمت إضافة
- تمت إضافة
BillingClient.getBillingConfigAsync()
لاسترداد البلد في Google Play.
الإصدار 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
.في الإصدار 6.0.0 من Play Billing Library، تمت الآن إزالة طريقة "
queryPurchases
" و"launchPriceConfirmationFlow
" التي تم وضع علامة عليها على أنّها متوقّفة نهائيًا. على المطوّرين استخدامqueryPurchasesAsync
بدلاً منqueryPurchases
. بالنسبة إلى بدائلlaunchPriceConfirmationFlow
، يمكنك الاطّلاع على تغييرات الأسعار.تمت إضافة رمز الاستجابة الجديد لخطأ في الشبكة.
تمت إضافة رمز استجابة جديد لخطأ في الشبكة،
NETWORK_ERROR
، بدءًا من الإصدار 6.0.0 من PBL. يتم عرض هذا الرمز عند حدوث خطأ بسبب مشكلة في الاتصال بالشبكة. تم الإبلاغ سابقًا عن أخطاء الاتصال هذه بالشبكة باسمSERVICE_UNAVAILABLE
.تم تعديل
SERVICE_UNAVAILABLE
وSERVICE_TIMEOUT
.بدءًا من الإصدار 6.0.0 من PBL، سيتم عرض الأخطاء الناتجة عن انتهاء مهلة المعالجة على أنّها
SERVICE_UNAVAILABLE
بدلاً منSERVICE_TIMEOUT
الحالي.لا يتغير السلوك في الإصدارات السابقة من PBL.
تمت إزالة
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.
ملخص التغييرات
- تمت إضافة صفوف لدعم تدفقات نظام الفوترة البديل على الأجهزة الجوّالة/الجهاز اللوحي للمستخدمين في كوريا الجنوبية:
- تمت إضافة طريقة
BillingFlowParams.SubscriptionUpdateParams.Builder.setOriginalExternalTransactionId()
لتحديد معرِّف المعاملة الخارجي للاشتراك المنشأ. - تمت إضافة طريقة
BillingClient.Builder.enableAlternativeBilling()
للسماح للمستخدمين في كوريا الجنوبية بتحديد خيار نظام فوترة بديل.
الإصدار 5.1 من Google Play Billing Library (31/10/2022)
يتوفّر الآن الإصدار 5.1.0 من Google Play Billing Library وإضافات Kotlin.
يحتوي هذا الإصدار على التغييرات التالية.
ملخص التغييرات
- تمت إضافة طريقة
ProductDetails.SubscriptionOfferDetails.getOfferId()
لاسترداد معرّف العرض. - تمت إضافة طريقة
ProductDetails.SubscriptionOfferDetails.getBasePlanId()
لاسترداد رقم تعريف الخطة الأساسية. - تم تعديل
targetSdkVersion
إلى 31.
الإصدار 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 Billing Library (18/05/2021)
يتوفّر الآن الإصدار 4.0.0 من Google Play Billing Library وإضافات Kotlin.
ملخص التغييرات
تمت إضافة
BillingClient.queryPurchasesAsync()
لاستبدالBillingClient.queryPurchases()
والتي ستتم إزالتها في إصدار مستقبلي.تمت إضافة وضع استبدال الاشتراك الجديد
IMMEDIATE_AND_CHARGE_FULL_PRICE
.تمت إضافة طريقة
BillingClient.getConnectionState()
لاسترداد حالة الاتصال بمكتبة الفوترة في Play.تم تعديل لغة JavaScript وتنفيذها للإشارة إلى سلسلة المحادثات التي يمكن الاستعانة بها ونتائج سلاسل المحادثات التي يتم نشرها.
تمت إضافة
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 Billing Library (12/03/2021)
يتوفّر الآن الإصدار 3.0.3 من Google Play Billing Library وإضافة Kotlin والمكوّن الإضافي Unity.
إصلاحات أخطاء Java وKotlin
- إصلاح تسرُّب الذاكرة عند استدعاء
endConnection()
. - يمكنك حل المشكلة عند استخدام Google Play Billing Library من خلال التطبيقات التي تستخدم
وضع تشغيل المهمة الواحدة. سيتم تشغيل معاودة الاتصال
onPurchasesUpdated()
عند استئناف تطبيق من مشغِّل تطبيقات Android وظهور مربّع حوار الفوترة قبل تعليق التطبيق.
إصلاحات أخطاء Unity
- يُرجى التحديث إلى الإصدار 3.0.3 من لغة Java لإصلاح تسرُّب الذاكرة وحل المشكلة التي تمنع عمليات الشراء عند استئناف تشغيل تطبيق من مشغّل Android وظهور مربع حوار الفوترة قبل تعليقه.
الإصدار 3.0.2 من Google Play Billing Library (24/11/2020)
يتوفّر الآن الإصدار 3.0.2 من Google Play Billing Library وإضافة Kotlin.
إصلاح الأخطاء
- تم إصلاح خطأ في إضافة Kotlin حيث يفشل الكوروتين مع ظهور الخطأ "سبق أن تم استئنافه".
- تم إصلاح المراجع التي لم يتم حلها عند استخدام إضافة Kotlin مع الإصدار 1.4 من مكتبة kotlinx.coroutines أو الإصدارات الأحدث.
الإصدار 3.0.1 من Google Play Billing Library (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 Billing Library (20/05/2020)
يتوفّر الآن الإصدار 2.2.1 من "مكتبة الفوترة في Google Play".
إصلاح الأخطاء
- تم تعديل الإصدار التلقائي من مكتبة Java Play Billing Library الذي تعتمد عليه إضافة Kotlin.
إصدار 2.2.0 من Google Play Billing Library ودعم Unity (23/03/2020)
يوفّر الإصدار 2.2.0 من "الفوترة في Google Play" وظائف تساعد مطوّري البرامج في ضمان نسب عمليات الشراء إلى المستخدم الصحيح. تلغي هذه التغييرات الحاجة إلى إنشاء حلول مخصّصة بناءً على حمولة المطوّرين. في إطار هذا التحديث، تم إيقاف وظيفة حمولة البيانات الخاصة بالمطوّر نهائيًا وستتم إزالتها في إصدار مستقبلي. لمزيد من المعلومات، بما في ذلك البدائل الموصى بها، يُرجى الاطّلاع على حمولة المطوّرين.
الإصدار 2 من Google Play Billing Library لنظام Unity
بالإضافة إلى الإصدارَين الحاليَين من Java وKotlin من Google Play Billing Library 2، لقد أطلقنا نسخة من المكتبة لاستخدامها مع Unity. يستطيع مطوّرو الألعاب الذين يستخدمون واجهة برمجة التطبيقات Unity للشراء داخل التطبيق الترقية الآن للاستفادة من جميع ميزات Google Play Billing Library 2 وتسهيل عمليات الترقية اللاحقة إلى الإصدارات المستقبلية من Google Play Billing Library.
لمزيد من المعلومات، راجِع استخدام خدمة "الفوترة في Google Play" من خلال Unity.
ملخص التغييرات
- مكتبة الفوترة في Google Play بلغة Java
- في طريقة
AcknowledgePurchaseParams
، تم إيقافها نهائيًاsetDeveloperPayload()
وطرقgetDeveloperPayload()
الخاصة. - في طريقة
ConsumeParams
، تم إيقافها نهائيًاsetDeveloperPayload()
وطرقgetDeveloperPayload()
الخاصة. - في
BillingFlowParams
، تمت إعادة تسميةsetAccountId()
إلىsetObfuscatedAccountId()
، وتم توثيق الحد الأقصى لعدد الأحرف البالغ 64 حرفًا وتقييده، مما يمنع منع معلومات تحديد الهوية الشخصية (PII) في هذا الحقل. تم وضع علامة علىsetAccountId()
على أنّه متوقّف نهائيًا وستتم إزالته في إصدار مكتبة في المستقبل. - في
BillingFlowParams
، تمت إضافةsetObfuscatedProfileId()
الذي يعمل مثلsetObfuscatedAccountId()
. لمزيد من المعلومات، راجِع تعديلات حمولة بيانات المطوّرين والبدائل. - في
Purchase
، تمت إضافة طريقةgetAccountIdentifiers()
لعرض معرّفات الحساب التي تم تشويشها والتي تم تحديدها فيBillingFlowParams
. - في
BillingClient
، تم وضع علامة على طريقةloadRewardedSku()
متوقّفة نهائيًا كجزء من الإيقاف النهائي لرموز التخزين التعريفية التي تضم مكافأة. يمكنك الاطّلاع على المزيد من المعلومات حول عملية الإيقاف النهائي في مركز مساعدة Play Console.
- في طريقة
إصدار 2.1.0 من Google Play Billing Library وإصدار 2.1.0 لإضافة Kotlin (2019-12-10)
يتوفّر الآن الإصدار 2.1.0 من مكتبة "الفوترة في Google Play" وإضافة Kotlin الجديدة. توفّر إضافة Kotlin لمكتبة الفوترة في Play بدائل واجهات برمجة تطبيقات اصطلاحية لاستهلاك لغة Kotlin، بما في ذلك مستوى أمان خالٍ وفرص أفضل للكوروتين. للحصول على أمثلة على الرموز البرمجية، يُرجى الاطّلاع على استخدام Google Play Billing Library.
يحتوي هذا الإصدار على التغييرات التالية.
ملخص التغييرات
- في
BillingFlowParams
، تم إيقافsetOldSku(String oldSku)
نهائيًا واستبدالهsetOldSku(String oldSku, String purchaseToken)
، لتوضيح ما إذا كانت حسابات متعددة على الجهاز تمتلك رمز التخزين التعريفي نفسه.
الإصدار 2.0.3 من Google Play Billing Library (05/08/2019)
يتوفّر الآن الإصدار 2.0.3 من "مكتبة الفوترة في Google Play".
إصلاح الأخطاء
- تم إصلاح الخطأ الذي يخفق فيه
querySkuDetailsAsync()
في بعض الأحيان عند استخدام الرمزDEVELOPER_ERROR
بدلاً من عرض نتيجة ناجحة.
الإصدار 2.0.2 من Google Play Billing Library (08/07/2019)
يتوفّر الآن الإصدار 2.0.2 من "مكتبة الفوترة في Google Play". يشتمل هذا الإصدار على تحديثات للوثائق المرجعية ولا يغير وظائف المكتبة.
الإصدار 2.0.1 من Google Play Billing Library (06/06/2019)
يتوفّر الآن الإصدار 2.0.1 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
إصلاح الأخطاء
- تم إصلاح الخطأ المتمثل في عرض رسائل تصحيح الأخطاء باسم
null
في بعض الحالات. - تم إصلاح مشكلة محتملة لتسرّب الذاكرة.
الإصدار 2.0 من Google Play Billing Library (07/05/2019)
يتوفّر الآن الإصدار 2.0 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
يجب الإقرار بعمليات الشراء في غضون ثلاثة أيام
يتيح Google Play شراء المنتجات من داخل تطبيقك (داخل التطبيق) أو
خارجه (خارج التطبيق). لضمان توفير تجربة شراء متسقة في Google Play بغض النظر عن المكان الذي يشتري فيه المستخدم منتجك، عليك الإقرار بجميع عمليات الشراء التي تتلقّاها من خلال "مكتبة الفوترة في Google Play" في أقرب وقت ممكن بعد منح المستخدم إذن الوصول إلى المنتج. وفي حال عدم إقرارك بعملية الشراء في غضون ثلاثة أيام، يسترد المستخدم الأموال تلقائيًا ويلغي 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()
،
وتمرير عنصر
SkuDetails
الناتج إلى
BillingFlowParams.Builder.setSkuDetails()
.
للحصول على أمثلة على الرموز البرمجية، يُرجى الاطّلاع على استخدام Google Play Billing Library.
يتم دعم الحمولة في حساب المطوّر.
يضيف الإصدار 2.0 من "مكتبة الفوترة في Google Play" الدعم للحمولة الأساسية، وهي سلاسل عشوائية يمكن إرفاقها بعمليات الشراء. يمكنك إرفاق مَعلمة حمولة البيانات للمطوّر بعملية شراء، ولكن فقط عند الإقرار بعملية الشراء أو استهلاكها. يختلف ذلك عن حمولة المطوّرين في AIDL، حيث يمكن تحديد الحمولة عند بدء مسار الشراء. بما أنّه يمكن الآن بدء عمليات الشراء من خارج تطبيقك، يضمن هذا التغيير أن تتوفّر لك دائمًا فرصة لإضافة حمولة إلى عمليات الشراء.
للوصول إلى الحمولة في المكتبة الجديدة، تتضمن كائنات Purchase
الآن طريقة
getDeveloperPayload()
.
تقديم عروض منتظمة
عندما تقدّم رمز تخزين تعريفي بسعر مخفَّض، يعرض Google Play الآن السعر الأصلي لرمز التخزين التعريفي حتى تتمكّن من إعلام المستخدمين بأنّهم يتلقّون هذا الخصم.
يحتوي SkuDetails
على
طريقتَين جديدتَين لاسترداد سعر رمز التخزين التعريفي الأصلي:
getOriginalPriceAmountMicros()
: لعرض السعر الأصلي غير المنسَّق لرمز التخزين التعريفي قبل الخصم.getOriginalPrice()
- لعرض السعر الأصلي مع تنسيق عملة إضافي.
المعاملات المعلّقة:
من خلال الإصدار 2.0 من "مكتبة الفوترة في Google Play"، يجب إتاحة عمليات الشراء التي تتطلب اتّخاذ إجراء إضافي قبل منح إذن الوصول إلى التطبيق. على سبيل المثال، قد يختار المستخدم شراء المنتج داخل التطبيق في متجر فعلي باستخدام النقد. هذا يعني أنّ المعاملة تكتمل خارج نطاق تطبيقك. في هذا السيناريو، يجب عدم منح الإذن بالوصول إلا بعد إكمال المستخدم للمعاملة.
لتفعيل عمليات الشراء المعلّقة، اتصل بالرمز
enablePendingPurchases()
كجزء من إعداد تطبيقك.
يمكنك استخدام Purchase.getPurchaseState()
لتحديد ما إذا كانت حالة الشراء هي PURCHASED
أو PENDING
. يُرجى العلم أنّه
يجب عدم منح الإذن بالوصول إلا إذا كانت الولاية هي PURCHASED
. عليك البحث عن تحديثات حالة Purchase
من خلال اتّباع الخطوات التالية:
- عند بدء تشغيل تطبيقك، اطلب من التطبيق
BillingClient.queryPurchases()
استرداد قائمة المنتجات غير الاستهلاكية المرتبطة بالمستخدم. - استدعِ "
Purchase.getPurchaseState()
" على كل عنصر من عناصرPurchase
يتم عرضه. - نفِّذ الإجراء
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 Library على عدة تغييرات في واجهة برمجة التطبيقات لإتاحة الميزات الجديدة وتوضيح الوظائف الحالية.
ConumeAsync
تأخذ consumeAsync()
الآن كائن
ConsumeParams
بدلاً من purchaseToken
. يحتوي ConsumeParams
على purchaseToken
بالإضافة إلى حمولة بيانات مطوّرين اختيارية.
تمت إزالة الإصدار السابق من "consumeAsync()
" في هذا الإصدار.
queryPurchaseHistoryAsync
للحدّ من الالتباس، تعرض دالة queryPurchaseHistoryAsync()
الآن كائن PurchaseHistoryRecord
بدلاً من كائن Purchase
. الكائن PurchaseHistoryRecord
هو نفسه كائن Purchase
، باستثناء أنّه لا يعكس سوى القيم التي يعرضها queryPurchaseHistoryAsync()
ولا يحتوي على الحقول autoRenewing
وorderId
وpackageName
. لاحِظ أنّه لم يحدث أي تغيير في البيانات التي تم عرضها، لأنّ queryPurchaseHistoryAsync()
يعرض البيانات نفسها كما في السابق.
قيم إرجاع BillingResult
إنّ واجهات برمجة التطبيقات التي عرضت في السابق قيمة عدد صحيح BillingResponse
تعرض الآن عنصر
BillingResult
. يحتوي BillingResult
على العدد الصحيح BillingResponse
، بالإضافة إلى
سلسلة تصحيح أخطاء يمكنك استخدامها لتشخيص الأخطاء. تستخدم سلسلة تصحيح الأخطاء لغة en-US
ولا تهدف إلى عرضها للمستخدمين النهائيين.
إصلاح الأخطاء
- تعرض
SkuDetails.getIntroductoryPriceAmountMicros()
الآنlong
بدلاً منString
.
الإصدار 1.2.2 من Google Play Billing Library (07/03/2019)
يتوفّر الآن الإصدار 1.2.2 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
إصلاح الأخطاء
- تمت معالجة مشكلة في سلاسل المحادثات التي تم طرحها في الإصدار 1.2.1. لم تعد المكالمات في الخلفية تحظر سلسلة التعليمات الرئيسية.
تغييرات أخرى
- ومع أنّ استخدام سلسلة التعليمات الرئيسية لا يزال مستحسنًا، يمكنك الآن إنشاء مثيل "مكتبة الفوترة في Google Play" من سلسلة محادثات في الخلفية.
- تم نقل بيانات المثيل بالكامل إلى سلسلة التعليمات في الخلفية لتقليل فرصة التسبّب في أخطاء ANR.
الإصدار 1.2.1 من Play Billing Library (04/03/2019)
يتوفّر الآن الإصدار 1.2.1 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
التغييرات الرئيسية
- تمت إضافة دعم للمنتجات التي تتم مكافأتها. للمزيد من المعلومات حول خيارات تحقيق الربح، يُرجى الاطّلاع على إضافة ميزات خاصة بالمنتجات التي تضمّ مكافآت.
تغييرات أخرى
- تمت إضافة منصات إنشاء عامة لـ
PurchasesResult
وSkuDetailsResult
لتسهيل الاختبار. - يمكن لكائنات
SkuDetails
استخدام طريقة جديدة، وهيgetOriginalJson()
. - يتم الآن التعامل مع جميع طلبات خدمة AIDL من خلال سلاسل المحادثات في الخلفية.
إصلاح الأخطاء
- لم يعُد يتم تمرير أدوات معالجة معاودة الاتصال الفارغة إلى واجهات برمجة التطبيقات العامة.
الإصدار 1.2 من Google Play Billing Library (18/10/2018)
يتوفّر الآن الإصدار 1.2 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
ملخص التغييرات
- تم ترخيص Google Play Billing Library الآن بموجب اتفاقية ترخيص أدوات تطوير البرامج Android (Android Software Development Kit).
- تمت إضافة واجهة برمجة التطبيقات
launchPriceChangeConfirmationFlow
، والتي تطلب من المستخدمين مراجعة تغيير معلَّق لسعر الاشتراك. - تمت إضافة الدعم لوضع تقسيم نسبي جديد، وهو
DEFERRED
، عند ترقية اشتراك المستخدم أو الرجوع إلى إصدار سابق منه. - تم استبدال الصف
setSku()
بـsetSkuDetails()
في الصفBillingFlowParams
. - إصلاح أخطاء بسيطة وتحسينات على الرموز البرمجية
تأكيد تغيير السعر
يمكنك الآن تغيير سعر الاشتراك في 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
، تم
إيقاف الإجراء 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 Billing Library (07-05-2018)
يتوفّر الآن الإصدار 1.1 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
ملخص التغييرات
- تمت إضافة الدعم لتحديد وضع التوزيع التناسبي في
BillingFlowParams
عند ترقية اشتراك حالي أو الرجوع إلى إصدار سابق منه. - لم تعُد العلامة المنطقية
replaceSkusProration
فيBillingFlowParams
متاحة. يمكنك استخدامreplaceSkusProrationMode
كبديل. - يؤدي تفعيل
launchBillingFlow()
الآن إلى معاودة الاتصال للردود التي تعذّر إكمالها.
التغييرات في السلوك
يحتوي الإصدار 1.1 من Google Play Billing Library على تغييرات السلوك التالية:
يمكن للمطوِّرين إعداد 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()
الآن إلى معاودة الاتصال للردود التي تعذّر إكمالها.
ستفعّل "مكتبة الفوترة" دائمًا معاودة الاتصال بـ PurhcasesUpdatedListener
وتعرض BillingResponse
بشكل غير متزامن. ويتم أيضًا الاحتفاظ بالقيمة المتزامنة لـ BillingResponse
.
إصلاح الأخطاء
- يتم الخروج بشكل صحيح في وقت مبكر من الطرق غير المتزامنة عند انقطاع الخدمة.
- لم تعد كائنات المَعلمات
Builder
تغير الكائنات المنشأة. - المشكلة 68087141: يؤدي
launchBillingFlow()
الآن إلى معاودة الاتصال عند تعذّر الرد.
الإصدار 1.0 من Google Play Billing Library (19-09-2017، إعلان)
يتوفّر الآن الإصدار 1.0 من "مكتبة الفوترة في Google Play". يحتوي هذا الإصدار على التغييرات التالية.
التغييرات المهمة
- تم تضمين إذن الفوترة في ملف بيان المكتبة. ليس من الضروري إضافة
إذن
com.android.vending.BILLING
في بيان Android بعد الآن. - تمت إضافة أداة إنشاء جديدة إلى
الصف
BillingClient.Builder
. - تم تقديم نمط أداة إنشاء الفئة
SkuDetailsParams
للاستخدام في طرق طلب رموز التخزين التعريفية. - تم تحديث العديد من طرق واجهة برمجة التطبيقات لتحقيق الاتساق (نفس أسماء وسيطات العرض وترتيبها).
التغييرات في السلوك
يحتوي الإصدار 1.0 من Google Play Billing Library على تغييرات السلوك التالية:
فئة BillingClient.Builder
يتم إعداد BillingClient.Builder
الآن من خلال نمط newBuilder:
Kotlin
billingClient = BillingClient.newBuilder(context).setListener(this).build()
Java
billingClient = BillingClient.newBuilder(context).setListener(this).build();
يُطلق الآن على طريقة stationالفوترةFlow باستخدام فئة 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()
في نمط أداة إنشاء:
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)
إصلاح الأخطاء
- ما مِن رمز استجابة في الحزمة PURCHASES_UPDATED
- إصلاح مشاكل ProxybillingActivity وPurchasesupdatedListener أثناء تدوير الجهاز
إصدار معاينة المطوّر 1 (12-06-2017، إعلان)
تم إطلاق ميزة "معاينة المطوِّر" بهدف تبسيط عملية التطوير عندما يتعلق الأمر بالفوترة، ما يسمح للمطوّرين بتركيز جهودهم على تنفيذ المنطق الخاص بتطبيق Android، مثل بنية التطبيقات وبنية التنقّل.
تتضمن المكتبة عدة صفوف وميزات مناسبة لك لاستخدامها عند دمج تطبيقات Android مع واجهة برمجة التطبيقات Google Play Billing API. توفّر المكتبة أيضًا طبقة تجريدية أعلى خدمة "لغة تعريف واجهة Android (AIDL)"، ما يسهّل على المطوّرين تحديد الواجهة بين التطبيق وGoogle Play Billing API.