عندما يؤدي طلب من Play Billing Library إلى تنفيذ إجراء، تعرض المكتبة استجابة BillingResult لإعلام المطوّرين بالنتيجة. على سبيل المثال،
إذا كنت تستخدم queryProductDetailsAsync للحصول على العروض المتاحة
للمستخدم، يحتوي رمز الاستجابة إما على رمز OK ويوفّر كائن
ProductDetails الصحيح، أو يحتوي على استجابة مختلفة تشير إلى
سبب عدم توفير كائن ProductDetails.
ليست كل رموز الاستجابة أخطاء. تقدّم صفحة مرجع BillingResponseCode وصفًا تفصيليًا لكل ردّ من الردود التي تمت مناقشتها في هذا الدليل. في ما يلي بعض الأمثلة على رموز الاستجابة التي لا تشير إلى أخطاء:
BillingClient.BillingResponseCode.OK: تم إكمال الإجراء الذي تم تنفيذه من خلال الطلب بنجاح.BillingClient.BillingResponseCode.USER_CANCELED: بالنسبة إلى الإجراءات التي تعرض سلاسل إجراءات واجهة المستخدم في "متجر Google Play" للمستخدم، تشير هذه الاستجابة إلى أنّ المستخدم انتقل بعيدًا عن سلاسل إجراءات واجهة المستخدم هذه بدون إكمال العملية.
عندما يشير رمز الاستجابة إلى خطأ، يكون السبب أحيانًا هو
حالات عابرة، وبالتالي يمكن استرداد البيانات. عندما يؤدي طلب إجراء في Play
Billing Library إلى عرض قيمة BillingResponseCode تشير إلى
حالة يمكن إصلاحها، عليك إعادة محاولة الطلب. وفي حالات أخرى، لا تُعتبر الشروط عابرة، وبالتالي لا يُنصح بإعادة المحاولة.
تتطلّب الأخطاء المؤقتة استراتيجيات مختلفة لإعادة المحاولة بناءً على عوامل مثل
ما إذا كان الخطأ يحدث أثناء جلسة المستخدم، على سبيل المثال، عندما يمر المستخدم
بمسار شراء، أو يحدث الخطأ في الخلفية، على سبيل المثال،
عندما تستعلم عن عمليات الشراء الحالية للمستخدم أثناء
onResume. يقدّم قسم استراتيجيات إعادة المحاولة أمثلة على هذه الاستراتيجيات المختلفة، ويقترح قسم BillingResultالاستجابات التي يمكنك إعادة محاولة إرسالها الاستراتيجية الأفضل لكل رمز استجابة.
بالإضافة إلى رمز الاستجابة، تتضمّن بعض ردود الخطأ رسائل لأغراض تصحيح الأخطاء والتسجيل.
استراتيجيات إعادة المحاولة
إعادة المحاولة البسيطة
في الحالات التي يكون فيها المستخدم في جلسة، من الأفضل تنفيذ استراتيجية بسيطة لإعادة المحاولة حتى لا يؤدي الخطأ إلى تعطيل تجربة المستخدم قدر الإمكان. في هذه الحالة، ننصحك باتّباع استراتيجية بسيطة لإعادة المحاولة مع تحديد حدّ أقصى لعدد المحاولات كشرط للخروج.
يوضّح المثال التالي استراتيجية بسيطة لإعادة المحاولة من أجل معالجة خطأ
عند إنشاء اتصال BillingClient:
// Initialize the BillingClient. private val billingClient = BillingClient.newBuilder(context) .setListener(this) .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()) .build() private val coroutineScope = kotlinx.coroutines.CoroutineScope( kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.Main.immediate ) private var connectionJob: kotlinx.coroutines.Job? = null // Establish a connection to Google Play. fun startBillingConnection() { connectionJob?.cancel() connectionJob = coroutineScope.launch { connectWithRetry() } } // Suspended helper to perform a single connection attempt private suspend fun connectBilling(): BillingResult = kotlinx.coroutines.suspendCancellableCoroutine { continuation -> billingClient.startConnection(object : BillingClientStateListener { override fun onBillingSetupFinished(billingResult: BillingResult) { if (continuation.isActive) { continuation.resume(billingResult) } } override fun onBillingServiceDisconnected() { Log.e(TAG, "Google Play Billing Service disconnected") if (continuation.isActive) { continuation.resume( BillingResult.newBuilder() .setResponseCode(BillingClient.BillingResponseCode.SERVICE_DISCONNECTED) .setDebugMessage("Service disconnected during connection setup") .build() ) } else { startBillingConnection() } } }) } // Billing connection retry logic. This is a simple max retry pattern private suspend fun connectWithRetry() { val maxTries = 3 var tries = 1 var isConnectionEstablished = false while (tries <= maxTries && !isConnectionEstablished) { val billingResult = connectBilling() if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) { isConnectionEstablished = true Log.d(TAG, "Billing response OK") } else { Log.e(TAG, "Billing connection retry failed: ${billingResult.debugMessage}") tries++ if (tries <= maxTries) { delay(2000L) // Wait 2 seconds before retrying } } } } fun cleanUp() { coroutineScope.cancel() } // ...
إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي
ننصح باستخدام استراتيجية التراجع الأسي لعمليات Play Billing Library التي تحدث في الخلفية ولا تؤثر في تجربة المستخدم أثناء جلسة الاستخدام.
على سبيل المثال، سيكون من المناسب تنفيذ ذلك عند تأكيد عمليات الشراء الجديدة لأنّ هذه العملية يمكن أن تحدث في الخلفية، ولا يلزم إجراء التأكيد في الوقت الفعلي في حال حدوث خطأ.
private suspend fun acknowledge(purchaseToken: String): BillingResult = kotlinx.coroutines.suspendCancellableCoroutine { continuation -> val params = AcknowledgePurchaseParams.newBuilder() .setPurchaseToken(purchaseToken) .build() billingClient.acknowledgePurchase(params) { billingResult -> continuation.resumeWith(Result.success(billingResult)) } } private suspend fun queryPurchases(productType: String): Pair<BillingResult, List<Purchase>> = kotlinx.coroutines.suspendCancellableCoroutine { continuation -> val params = QueryPurchasesParams.newBuilder() .setProductType(productType) .build() billingClient.queryPurchasesAsync(params) { billingResult, purchaseList -> continuation.resumeWith(Result.success(Pair(billingResult, purchaseList))) } } suspend fun acknowledgePurchase(purchaseToken: String) { val retryDelayMs = 2000L val retryFactor = 2 val maxTries = 3 var tries = 1 var currentDelay = retryDelayMs var acknowledgePurchaseResult: BillingResult do { acknowledgePurchaseResult = acknowledge(purchaseToken) val playBillingResponseCode = acknowledgePurchaseResult.responseCode when (playBillingResponseCode) { BillingClient.BillingResponseCode.OK -> { Log.i(TAG, "Acknowledgement was successful") return } BillingClient.BillingResponseCode.ITEM_NOT_OWNED -> { Log.d(TAG, "Acknowledgement failed with ITEM_NOT_OWNED") val (billingResult, purchaseList) = queryPurchases(BillingClient.ProductType.SUBS) if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) { purchaseList.forEach { purchase -> acknowledge(purchase.purchaseToken) } } return } in setOf( BillingClient.BillingResponseCode.ERROR, BillingClient.BillingResponseCode.SERVICE_DISCONNECTED, BillingClient.BillingResponseCode.SERVICE_UNAVAILABLE, ) -> { Log.d( TAG, "Acknowledgement failed, but can be retried -- " + "Response Code: ${acknowledgePurchaseResult.responseCode} -- " + "Debug Message: ${acknowledgePurchaseResult.debugMessage}" ) if (tries < maxTries) { delay(currentDelay) currentDelay *= retryFactor tries++ } else { break } } else -> { Log.e( TAG, "Acknowledgement failed and cannot be retried -- " + "Response Code: ${acknowledgePurchaseResult.responseCode} -- " + "Debug Message: ${acknowledgePurchaseResult.debugMessage}" ) throw Exception("Failed to acknowledge the purchase!") } } } while (tries <= maxTries) throw Exception("Failed to acknowledge the purchase after $maxTries attempts!") }
استجابات BillingResult التي يمكنك إعادة محاولتها
NETWORK_ERROR (رمز الخطأ 12)
المشكلة
يشير هذا الخطأ إلى حدوث مشكلة في الاتصال بالشبكة بين الجهاز وأنظمة Play.
الحل المحتمل
للاسترداد، استخدِم عمليات إعادة المحاولة البسيطة أو التراجع الأسي، حسب الإجراء الذي أدّى إلى حدوث الخطأ.
SERVICE_TIMEOUT (رمز الخطأ -3)
المشكلة
يشير هذا الخطأ إلى أنّ الطلب قد وصل إلى الحد الأقصى للمهلة قبل أن يتمكّن Google Play من الردّ. قد يكون السبب في ذلك، على سبيل المثال، تأخير في تنفيذ الإجراء المطلوب من خلال طلب البيانات من Play Billing Library.
الحل المحتمل
هذه عادةً مشكلة عابرة. أعِد محاولة إرسال الطلب باستخدام استراتيجية التراجع البسيط أو الأسي، وذلك حسب الإجراء الذي أدّى إلى ظهور الخطأ.
على عكس SERVICE_DISCONNECTED، لا يتم قطع الاتصال بخدمة "الفوترة في Google Play"، وعليك فقط إعادة محاولة تنفيذ أي عملية في Play Billing Library.
SERVICE_DISCONNECTED (رمز الخطأ -1)
المشكلة
يشير هذا الخطأ الفادح إلى انقطاع اتصال تطبيق العميل بخدمة "متجر Google Play" باستخدام BillingClient.
الحل المحتمل
ننصح بشدة بتفعيل ميزة "إعادة الاتصال التلقائي بالخدمة"
يقدّم الإصدار 8.0.0 من واجهة Google Play Billing Library ميزة
enableAutoServiceReconnection().
ننصحك بشدة بتفعيل هذه الميزة عند إنشاء
BillingClient. يتيح ذلك للمكتبة محاولة إعادة إنشاء الاتصال تلقائيًا عند إجراء طلب بيانات من واجهة برمجة التطبيقات للفوترة أثناء انقطاع الخدمة، ما يقلل بشكل كبير من حدوث هذا الخطأ.
Kotlin
val billingClient = BillingClient.newBuilder(context) .setListener(listener) .enablePendingPurchases( PendingPurchasesParams.newBuilder().enableOneTimeProducts().build() ) .enableAutoServiceReconnection() // Enable automatic service reconnection .build()
Java
BillingClient billingClient = BillingClient.newBuilder(context)
.setListener(listener)
.enablePendingPurchases()
.enableAutoServiceReconnection() // Enable automatic service reconnection
.build();
في حال تفعيل إعادة الاتصال التلقائي بالخدمة
ستحاول Play Billing Library إعادة الاتصال تلقائيًا. إذا استمر ظهور رمز الاستجابة SERVICE_DISCONNECTED عند طلب بيانات من واجهة برمجة التطبيقات، يشير ذلك إلى أنّ المكتبة لم تتمكّن من إعادة الاتصال بعد محاولاتها التلقائية.
في هذا السيناريو، عليك تنفيذ منطق إعادة المحاولة في تطبيقك:
- بالنسبة إلى الإجراءات التي يبدأها المستخدم (أثناء الجلسة): استخدِم عمليات إعادة المحاولة البسيطة لطلب بيانات من واجهة برمجة التطبيقات. قد تكون المشكلة الأساسية مؤقتة.
- بالنسبة إلى الطلبات في الخلفية: يمكنك تنفيذ عمليات إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي لتجنُّب إرباك النظام في حال استمرار انقطاع الاتصال لفترة طويلة.
في حال عدم تفعيل إعادة الاتصال التلقائي بالخدمة
لتجنُّب هذا الخطأ قدر الإمكان، تحقَّق دائمًا من الاتصال بـ "خدمات Google Play" قبل إجراء المكالمات باستخدام Play Billing Library من خلال الاتصال بـ BillingClient.isReady.
لمحاولة الاسترداد من SERVICE_DISCONNECTED، يجب أن يحاول تطبيق العميل إعادة إنشاء الاتصال باستخدام BillingClient.startConnection.
كما هو الحال مع SERVICE_TIMEOUT، استخدِم عمليات إعادة المحاولة البسيطة أو خوارزمية الرقود الأسي الثنائي، حسب الإجراء الذي أدّى إلى حدوث الخطأ.
SERVICE_UNAVAILABLE (رمز الخطأ 2)
ملاحظة مهمة:
اعتبارًا من الإصدار 6.0.0 من Google Play Billing Library، لن يتم عرض SERVICE_UNAVAILABLE
عند حدوث مشاكل في الشبكة. يتم عرض هذا الخطأ عندما تكون خدمة الفوترة غير متاحة وعند حدوث حالات SERVICE_TIMEOUT المتوقّفة نهائيًا.
المشكلة
يشير هذا الخطأ المؤقت إلى أنّ خدمة "الفوترة في Google Play" غير متاحة حاليًا. في معظم الحالات، يعني هذا أنّ هناك مشكلة في الاتصال بالشبكة بين جهاز العميل وخدمات "الفوترة في Google Play".
الحل المحتمل
وهذه عادةً مشكلة عابرة. أعِد محاولة إرسال الطلب باستخدام استراتيجية التراجع البسيط أو الأسي، وذلك حسب الإجراء الذي أدّى إلى ظهور الخطأ.
على عكس SERVICE_DISCONNECTED، لا يتم قطع الاتصال بخدمة "الفوترة في Google Play"، وعليك إعادة محاولة تنفيذ أي عملية يتم إجراؤها.
BILLING_UNAVAILABLE (رمز الخطأ 3)
المشكلة
يشير هذا الخطأ إلى حدوث خطأ في فوترة المستخدم أثناء عملية الشراء. تشمل الأمثلة على الحالات التي يمكن أن يحدث فيها ذلك ما يلي:
- إذا كان تطبيق "متجر Google Play" على جهاز المستخدم قديمًا.
- المستخدم في بلد غير متاح.
- إذا كان المستخدم من مستخدمي الإصدار الخاص بالمؤسسات، وكان مشرف المؤسسة قد أوقف إمكانية إجراء عمليات شراء للمستخدمين.
- يتعذّر على Google Play تحصيل الرسوم من طريقة الدفع التي يستخدمها المستخدم. على سبيل المثال، قد تكون صلاحية بطاقة الائتمان الخاصة بالمستخدم قد انتهت.
- تم حظر تطبيق "متجر Google Play" من قِبل النظام (على سبيل المثال، في وضع الأطفال المخصّص من قِبل المصنّع الأصلي للجهاز). في هذه الحالة، يتضمّن
BillingResultرسالة تصحيح الأخطاء تم حظر "متجر Google Play".
الحل المحتمل
من غير المرجّح أن تساعد عمليات إعادة المحاولة التلقائية في هذه الحالة. ومع ذلك، يمكن أن تساعد إعادة المحاولة يدويًا إذا عالج المستخدم الحالة التي تسببت في المشكلة. على سبيل المثال، إذا حدّث المستخدم إصدار "متجر Google Play" إلى إصدار متوافق، يمكن أن تنجح إعادة المحاولة يدويًا للعملية الأولية.
إذا حدث هذا الخطأ عندما لا يكون المستخدم في جلسة، قد لا تكون إعادة المحاولة منطقية. عندما تتلقّى الخطأ
BILLING_UNAVAILABLEنتيجةً لمسار الشراء، من المرجّح جدًا أنّ المستخدم قد تلقّى ملاحظات من Google Play أثناء عملية الشراء وقد يكون على عِلم بالمشكلة. في هذه الحالة، يمكنك عرض رسالة خطأ تحدّد حدوث خطأ وتقديم زر إعادة المحاولة لمنح المستخدم خيار إعادة المحاولة يدويًا بعد معالجة المشكلة.
خطأ (رمز الخطأ 6)
المشكلة
هذا خطأ فادح يشير إلى مشكلة داخلية في Google Play نفسه.
الحل المحتمل
في بعض الأحيان، تكون المشاكل الداخلية في Google Play التي تؤدي إلى حدوث الخطأ ERROR
مؤقتة، ويمكن إعادة المحاولة مع استخدام استراتيجية الانتظار الأسي
للحدّ من المشكلة. عندما يكون المستخدمون في جلسة، يُفضَّل إجراء إعادة محاولة بسيطة.
ITEM_ALREADY_OWNED
المشكلة
تشير هذه الاستجابة إلى أنّ مستخدم Google Play يملك بالفعل الاشتراك أو المنتج الذي يحاول شراءه لمرة واحدة. في معظم الحالات، لا يكون هذا الخطأ عابرًا، إلا إذا كان ناتجًا عن ذاكرة تخزين مؤقت قديمة في Google Play.
الحل المحتمل
لتجنُّب حدوث هذا الخطأ عندما لا يكون السبب مشكلة في ذاكرة التخزين المؤقت، لا تعرض
منتجًا للشراء إذا كان المستخدم يمتلكه من قبل. تأكَّد من التحقّق من
أذونات المستخدم عند عرض المنتجات المتاحة للشراء،
وفلترة ما يمكن للمستخدم شراؤه وفقًا لذلك.
عندما يتلقّى تطبيق العميل هذا الخطأ بسبب مشكلة في ذاكرة التخزين المؤقت، يؤدي الخطأ إلى تحديث ذاكرة التخزين المؤقت في Google Play بأحدث البيانات من الخلفية في Play.
من المفترض أن تؤدي إعادة المحاولة بعد حدوث الخطأ إلى حلّ هذه الحالة المؤقتة المحدّدة في هذه الحالة. يمكنك طلب BillingClient.queryPurchasesAsync() بعد الحصول على
ITEM_ALREADY_OWNED للتحقّق مما إذا كان المستخدم قد حصل على المنتج، وإذا
لم يكن الأمر كذلك، يمكنك تنفيذ منطق إعادة محاولة بسيط لإعادة محاولة الشراء.
ITEM_NOT_OWNED
المشكلة
تشير استجابة الشراء هذه إلى أنّ مستخدم Google Play لا يملك الاشتراك أو منتج عملية الشراء لمرة واحدة الذي يحاول المستخدم استبداله أو إعلام بالاستلام أو استهلاكه. لا يُعدّ هذا الخطأ عابرًا في معظم الحالات، إلا إذا كان ناتجًا عن وصول ذاكرة التخزين المؤقت في Google Play إلى حالة قديمة.
الحل المحتمل
عند تلقّي الخطأ بسبب مشكلة في ذاكرة التخزين المؤقت، يؤدي الخطأ إلى تحديث ذاكرة التخزين المؤقت في Google Play بأحدث البيانات من الخلفية في Play. من المفترض أن تؤدي إعادة المحاولة باستخدام استراتيجية بسيطة بعد حدوث الخطأ إلى حلّ هذه المشكلة المؤقتة. يمكنك طلب BillingClient.queryPurchasesAsync() بعد
الحصول على ITEM_NOT_OWNED للتحقّق مما إذا كان المستخدم قد حصل على المنتج.
وإذا لم تكن قد اكتملت، استخدِم منطق إعادة المحاولة البسيط لإعادة محاولة الشراء.
استجابات BillingResult غير القابلة لإعادة المحاولة
ولا يمكنك استرداد البيانات من هذه الأخطاء باستخدام منطق إعادة المحاولة.
FEATURE_NOT_SUPPORTED
المشكلة
يشير هذا الخطأ غير القابل لإعادة المحاولة إلى أنّ ميزة "الفوترة في Google Play" غير متاحة على جهاز المستخدم، وذلك على الأرجح بسبب استخدام إصدار قديم من "متجر Google Play".
على سبيل المثال، قد لا تتيح بعض أجهزة المستخدمين ميزة المراسلة داخل التطبيق.
إجراءات التخفيف المحتملة
استخدِم BillingClient.isFeatureSupported للتحقّق من توفّر الميزة قبل
إجراء المكالمة مع "مكتبة الفوترة في Play".
when { billingClient.isReady -> { val billingResult = billingClient.isFeatureSupported(BillingClient.FeatureType.IN_APP_MESSAGING) if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) { // use Feature } } }
USER_CANCELED
المشكلة
نقَر المستخدم خارج واجهة مستخدم مسار الفوترة.
الحل المحتمل
هذه المعلومات مخصّصة لأغراض إعلامية فقط ويمكن أن تفشل بسلاسة.
ITEM_UNAVAILABLE
المشكلة
لا يتوفّر اشتراك "الفوترة في Google Play" أو عملية شراء لمرة واحدة للشراء لهذا المستخدم.
إجراءات التخفيف المحتملة
تأكَّد من أنّ تطبيقك يعيد تحميل تفاصيل المنتج باستخدام
queryProductDetailsAsync على النحو المُقترَح. يجب مراعاة عدد مرات تغيير كتالوج المنتجات في إعدادات Play Console لتنفيذ عمليات إعادة تحميل إضافية إذا لزم الأمر.
لا تحاول بيع المنتجات على "الفوترة في Google Play" إلا إذا كانت تعرض المعلومات الصحيحة باستخدام queryProductDetailsAsync.
تحقَّق من إعدادات أهلية المنتج بحثًا عن أي حالات عدم اتساق.
على سبيل المثال، قد تطلب منتجًا متاحًا فقط في منطقة أخرى غير المنطقة التي يحاول المستخدم الشراء منها.
لتصبح المنتجات متاحة للشراء، يجب أن تكون نشطة وأن يكون التطبيق
منشورًا ومتاحًا في بلد المستخدم.
في بعض الأحيان، لا سيما أثناء الاختبار، يكون كل شيء صحيحًا في إعدادات المنتج، ولكن لا يزال المستخدمون يرون هذا الخطأ. قد يرجع ذلك إلى تأخير في نشر تفاصيل المنتج على خوادم Google. يُرجى إعادة المحاولة لاحقًا.
DEVELOPER_ERROR
المشكلة
هذا خطأ فادح يشير إلى أنّك تستخدم واجهة برمجة تطبيقات بشكل غير صحيح.
على سبيل المثال، قد يؤدي تقديم مَعلمات غير صحيحة إلى BillingClient.launchBillingFlow إلى حدوث هذا الخطأ.
الحل المحتمل
تأكَّد من استخدام طلبات Play Billing Library المختلفة بشكل صحيح. يُرجى أيضًا الاطّلاع على رسالة تصحيح الأخطاء للحصول على مزيد من المعلومات حول الخطأ.