مدیریت کدهای پاسخ BillingResult

وقتی فراخوانی «کتابخانه خدمات صورت‌حساب Play» کنشی را راه‌اندازی می‌کند، کتابخانه پاسخ BillingResult را برمی‌گرداند تا توسعه‌دهندگان را از نتیجه مطلع کند. برای مثال، اگر از queryProductDetailsAsync برای دریافت پیشنهادهای دردسترس برای کاربر استفاده کنید، کد پاسخ یا حاوی کد OK است و شیء ProductDetails مناسب را ارائه می‌دهد، یا حاوی پاسخ دیگری است که نشان‌دهنده دلیل عدم ارائه شیء ProductDetails است.

همه کدهای پاسخ خطا نیستند. صفحه مرجع BillingResponseCode شرح مفصلی از هریک از پاسخ‌های موردبحث در این راهنما ارائه می‌دهد. چند نمونه از کدهای پاسخ که نشان‌دهنده خطا نیستند:

  • BillingClient.BillingResponseCode.OK : کنش راه‌اندازی‌شده توسط تماس باموفقیت تکمیل شد.
  • BillingClient.BillingResponseCode.USER_CANCELED : برای کنش‌هایی که جریان‌های میانای کاربر «فروشگاه Play» را به کاربر نشان می‌دهند، این پاسخ نشان می‌دهد که کاربر بدون تکمیل فرایند از آن جریان‌های میانای کاربر خارج شده است.

وقتی کد پاسخ نشان‌دهنده خطا باشد، علت آن گاهی به‌دلیل شرایط گذرا است و بنابراین بازیابی امکان‌پذیر است. وقتی فراخوانی روش «کتابخانه خدمات صورت‌حساب Play» مقدار 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» که در پس‌زمینه اتفاق می‌افتد و بر تجربه کاربری درطول جلسه کاربر تأثیر نمی‌گذارد، از عقب‌نشینی نمایی استفاده کنید.

برای مثال، پیاده‌سازی این روش هنگام تأیید خریدهای جدید مناسب است، زیرا این عملیات می‌تواند در پس‌زمینه انجام شود و درصورت بروز خطا، نیازی به تأیید درلحظه نیست.

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 (کد خطا ۱۲)

مشکل

این خطا نشان می‌دهد که مشکلی در اتصال شبکه‌ای بین دستگاه و سیستم‌های Play وجود دارد.

وضوح احتمالی

برای بازیابی، بسته به اینکه کدام کنش باعث ایجاد خطا شده است، از تلاش مجدد ساده یا عقب‌گرد نمایی استفاده کنید.

SERVICE_TIMEOUT (کد خطا: ۳-)

مشکل

این خطا نشان می‌دهد که درخواست به حداکثر زمان مجاز رسیده است، قبل‌از اینکه Google Play بتواند پاسخ دهد. این مشکل می‌تواند به‌دلیل تأخیر در اجرای کنش درخواست‌شده توسط فراخوانی «کتابخانه خدمات صورت‌حساب Play» باشد.

وضوح احتمالی

این مشکل معمولاً گذرا است. درخواست را بااستفاده از استراتژی عقب‌نشینی ساده یا نمایی تکرار کنید، بسته به اینکه کدام کنش خطا را برگردانده است.

برخلاف SERVICE_DISCONNECTED، اتصال به سرویس «خدمات صورت‌حساب Google Play» قطع نمی‌شود و فقط باید هر عملیاتی را که «کتابخانه خدمات صورت‌حساب Google Play» تلاش کرده است انجام دهد دوباره امتحان کنید.

SERVICE_DISCONNECTED (کد خطا: ۱-)

مشکل

این خطای مهلک نشان می‌دهد که اتصال برنامه کارخواه به سرویس «فروشگاه Google Play» بااستفاده از BillingClient قطع شده است.

وضوح احتمالی

«کتابخانه خدمات صورت‌حساب Play» نسخه ۸.۰.۰ ویژگی enableAutoServiceReconnection() را معرفی کرد. به‌شدت توصیه می‌شود که این ویژگی را هنگام ساختن BillingClient فعال کنید. این کار به کتابخانه اجازه می‌دهد تا به‌طور خودکار تلاش کند اتصال را دوباره برقرار کند، وقتی که فراخوانی میانای برنامه‌سازی کاربردی صورت‌حساب درحالی‌که سرویس قطع است انجام می‌شود، که این امر وقوع این خطا را به‌طور قابل‌توجهی کاهش می‌دهد.

کاتلین

val billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases(
        PendingPurchasesParams.newBuilder().enableOneTimeProducts().build()
    )
    .enableAutoServiceReconnection() // Enable automatic service reconnection
    .build()

جاوا

BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Enable automatic service reconnection
    .build();
اگر اتصال مجدد خودکار سرویس را فعال کرده باشید

«کتابخانه صورت‌حساب Play» به‌طور خودکار تلاش می‌کند دوباره متصل شود. اگر همچنان هنگام برقراری تماس API کد پاسخ SERVICE_DISCONNECTED دریافت می‌کنید، نشان می‌دهد که کتابخانه نتوانسته است پس‌از تلاش‌های خودکارش دوباره متصل شود. در این سناریو، باید منطق تکرار را در برنامه‌تان پیاده‌سازی کنید:

  • برای کنش‌های شروع‌شده توسط کاربر (درون جلسه): از بازامتحان‌های ساده فراخوانی میانای برنامه‌سازی کاربردی استفاده کنید. مشکل اصلی ممکن است موقتی باشد.
  • برای درخواست‌های پس‌زمینه: برای جلوگیری از تحت‌فشار قرار گرفتن سیستم درصورت طولانی شدن قطع اتصال، تلاش‌های مجدد را با عقب‌گرد نمایی پیاده‌سازی کنید.
اگر اتصال مجدد خودکار سرویس را فعال نکرده باشید

برای جلوگیری از این خطا تا حد امکان، همیشه قبل‌از برقراری تماس با «کتابخانه صورت‌حساب Play» با فراخوانی BillingClient.isReady، اتصال به «خدمات Google Play» را بررسی کنید.

برای تلاش برای بازیابی از SERVICE_DISCONNECTED، برنامه کارخواه شما باید سعی کند اتصال را بااستفاده از BillingClient.startConnection دوباره برقرار کند.

درست مانند SERVICE_TIMEOUT، بسته به اینکه کدام کنش باعث ایجاد خطا شده است، از تلاش مجدد ساده یا عقب‌گرد نمایی استفاده کنید.

SERVICE_UNAVAILABLE (کد خطای ۲)

نکته مهم:

از «کتابخانه خدمات صورت‌حساب Google Play» نسخه ۶.۰.۰، SERVICE_UNAVAILABLE دیگر برای مشکلات شبکه برگردانده نمی‌شود. این خطا زمانی برگردانده می‌شود که سرویس صدور صورت‌حساب دردسترس نباشد و سناریوهای موردی SERVICE_TIMEOUT منسوخ شده باشند.

مشکل

این خطای گذرا نشان می‌دهد که سرویس «صورت‌حساب Google Play» درحال‌حاضر دردسترس نیست. در بیشتر موارد، این یعنی مشکلی در اتصال شبکه بین دستگاه کارخواه و خدمات صورت‌حساب Google Play وجود دارد.

وضوح احتمالی

این مشکل معمولاً گذرا است. درخواست را بااستفاده از استراتژی عقب‌نشینی ساده یا نمایی تکرار کنید، بسته به اینکه کدام کنش خطا را برگردانده است.

برخلاف SERVICE_DISCONNECTED، اتصال به سرویس «خدمات صورت‌حساب Google Play» قطع نمی‌شود و باید هر عملیاتی را که درحال انجام است دوباره امتحان کنید.

BILLING_UNAVAILABLE (کد خطای ۳)

مشکل

این خطا نشان می‌دهد که خطای صورت‌حساب کاربر درطول فرایند خرید رخ داده است. نمونه‌هایی از زمان وقوع این اتفاق عبارتند از:

  • برنامه «فروشگاه Play» در دستگاه کاربر قدیمی است.
  • کاربر در کشوری است که پشتیبانی نمی‌شود.
  • کاربر، کاربر سازمانی است و سرپرست سازمانی او امکان خرید را برای کاربران غیرفعال کرده است.
  • Google Play نمی‌تواند هزینه را از روش پرداخت کاربر کسر کند. برای مثال، ممکن است کارت اعتباری کاربر منقضی شده باشد.
  • برنامه «فروشگاه Play» توسط سیستم مسدود شده است (برای مثال، در حالت کودک سفارشی‌سازی‌شده توسط سازنده اصلی). در این حالت، BillingResult شامل پیام اشکال‌زدایی «فروشگاه Play» مسدود شده است است.

وضوح احتمالی

  • امتحان مجدد خودکار احتمالاً در این مورد کمکی نمی‌کند. بااین‌حال، اگر کاربر شرایطی را که باعث بروز مشکل شده است برطرف کند، امتحان مجدد دستی می‌تواند کمک کند. برای مثال، اگر کاربر نسخه «فروشگاه Play» خود را به نسخه پشتیبانی‌شده به‌روز کند، امتحان مجدد دستی عملیات اولیه می‌تواند کار کند.

  • اگر این خطا زمانی رخ دهد که کاربر در جلسه نیست، ممکن است امتحان مجدد منطقی نباشد. وقتی خطای BILLING_UNAVAILABLE را درنتیجه جریان خرید دریافت می‌کنید، احتمالاً کاربر درطول فرایند خرید بازخوردی از Google Play دریافت کرده است و ممکن است بداند مشکل از کجا بوده است. در این مورد، می‌توانید پیام خطایی نشان دهید که مشخص می‌کند مشکلی پیش آمده است و دکمه دوباره امتحان کنید را ارائه دهید تا کاربر بتواند پس‌از برطرف کردن مشکل، به‌صورت دستی دوباره امتحان کند.

خطا (کد خطا: ۶)

مشکل

این خطای مهلکی است که نشان‌دهنده مشکل داخلی در خود Google Play است.

وضوح احتمالی

گاهی اوقات مشکلات داخلی Google Play که منجر به ERROR می‌شوند گذرا هستند و برای کاهش این مشکلات می‌توان از امتحان مجدد با عقب‌نشینی نمایی استفاده کرد. وقتی کاربران در جلسه هستند، امتحان مجدد ساده ترجیح داده می‌شود.

ITEM_ALREADY_OWNED

مشکل

این پاسخ نشان می‌دهد که کاربر Google Play ازقبل مالک اشتراک یا محصول خرید یک‌باره‌ای است که می‌خواهد خریداری کند. در بیشتر موارد، این خطا گذرا نیست، مگر اینکه به‌دلیل حافظه نهان قدیمی Google Play ایجاد شده باشد.

وضوح احتمالی

برای جلوگیری از وقوع این خطا وقتی علت آن مشکل حافظه پنهان نیست، محصولی را که کاربر قبلاً مالک آن است برای خرید به او پیشنهاد ندهید. هنگام نمایش محصولات دردسترس برای خرید، حتماً حقوق کاربر را بررسی کنید و آنچه را کاربر می‌تواند خریداری کند براساس آن فیلتر کنید. وقتی برنامه کارخواه این خطا را به‌دلیل مشکل حافظه نهان دریافت می‌کند، خطا باعث می‌شود حافظه نهان Google Play با جدیدترین داده‌ها از پسای Play به‌روز شود. در این مورد، امتحان مجدد پس‌از خطا باید این نمونه گذرا را برطرف کند. پس‌از دریافت ITEM_ALREADY_OWNED، با BillingClient.queryPurchasesAsync() تماس بگیرید تا بررسی کنید آیا کاربر محصول را خریداری کرده است یا نه، و اگر خریداری نکرده است، منطق امتحان مجدد ساده‌ای را برای تلاش مجدد برای خرید پیاده‌سازی کنید.

ITEM_NOT_OWNED

مشکل

این پاسخ خرید نشان می‌دهد که کاربر Google Play مالک اشتراک یا محصول خرید یک‌باره‌ای که کاربر تلاش می‌کند جایگزین کند، تأیید کند، یا مصرف کند نیست. در بیشتر موارد، این خطا گذرا نیست، مگر اینکه به‌دلیل قدیمی شدن حافظه نهان Google Play ایجاد شده باشد.

وضوح احتمالی

وقتی خطا به‌دلیل مشکل حافظه نهان دریافت می‌شود، خطا باعث می‌شود حافظه نهان Google Play با جدیدترین داده‌ها از پس‌بایگانی Play به‌روز شود. امتحان مجدد با راهبرد امتحان مجدد ساده پس‌از خطا باید این نمونه گذرا را حل کند. پس‌از دریافت ITEM_NOT_OWNED، BillingClient.queryPurchasesAsync() را فراخوانی کنید تا بررسی کنید آیا کاربر محصول را خریداری کرده است یا نه. اگر این کار را نکرده‌اند، از منطق تکرار ساده برای تلاش مجدد برای خرید استفاده کنید.

پاسخ‌های Non-Retriable BillingResult

بااستفاده از منطق تکرار نمی‌توانید از این خطاها بازیابی کنید.

FEATURE_NOT_SUPPORTED

مشکل

این خطای غیرقابل‌تکرار نشان می‌دهد که ویژگی «خدمات صورت‌حساب Google Play» در دستگاه کاربر پشتیبانی نمی‌شود، احتمالاً به‌دلیل قدیمی بودن نسخه «فروشگاه Play».

برای مثال، شاید برخی‌از دستگاه‌های کاربران شما از پیام‌رسانی درون‌برنامه پشتیبانی نمی‌کنند.

کاهش احتمالی

قبل‌از برقراری تماس با «کتابخانه خدمات صورت‌حساب Play»، از BillingClient.isFeatureSupported برای بررسی پشتیبانی ویژگی استفاده کنید.

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» درنظر بگیرید تا درصورت نیاز، بازآوری‌های بیشتری را پیاده‌سازی کنید. فقط محصولاتی را در «خدمات صورت‌حساب Google Play» بفروشید که اطلاعات درست را بااستفاده از queryProductDetailsAsync برمی‌گردانند. پیکربندی واجدشرایط بودن محصول را برای هرگونه ناهماهنگی بررسی کنید. برای مثال، ممکن است محصولی را پُرسمان کنید که فقط برای منطقه‌ای غیراز منطقه‌ای که کاربر سعی دارد از آن خرید کند دردسترس است. برای اینکه محصولی برای خرید دردسترس باشد، باید فعال باشد، برنامه‌اش باید منتشر شده باشد، و برنامه‌اش باید در کشور کاربر دردسترس باشد.

گاهی اوقات، به‌ویژه درطول آزمایش، همه چیز در پیکربندی محصول درست است، اما کاربران همچنان این خطا را می‌بینند. این ممکن است به‌دلیل تأخیر در انتشار جزئیات محصول در سرورهای Google باشد. بعداً دوباره امتحان کنید.

DEVELOPER_ERROR

مشکل

این خطای مهلکی است که نشان می‌دهد از میانای برنامه‌سازی کاربردی به‌طور نادرست استفاده می‌کنید. برای مثال، ارائه پارامترهای نادرست به BillingClient.launchBillingFlow می‌تواند باعث این خطا شود.

وضوح احتمالی

مطمئن شوید که از فراخوانی‌های مختلف Play Billing Library به‌درستی استفاده می‌کنید. همچنین، برای اطلاعات بیشتر درباره خطا، پیام اشکال‌زدایی را بررسی کنید.