Mit BillingResult-Antwortcodes umgehen

Wenn ein Aufruf der Play Billing Library eine Aktion auslöst, gibt die Bibliothek eine BillingResult-Antwort zurück, um Entwickler über das Ergebnis zu informieren. Wenn Sie beispielsweise queryProductDetailsAsync verwenden, um die verfügbaren Angebote für den Nutzer abzurufen, enthält der Antwortcode entweder einen OK-Code und stellt das richtige ProductDetails-Objekt bereit oder er enthält eine andere Antwort, die den Grund angibt, warum das ProductDetails-Objekt nicht bereitgestellt werden konnte.

Nicht alle Antwortcodes sind Fehler. Die Referenzseite zu BillingResponseCode enthält eine detaillierte Beschreibung der einzelnen Antworten, die in diesem Leitfaden erläutert werden. Hier einige Beispiele für Antwortcodes, die nicht auf Fehler hinweisen:

Wenn der Antwortcode auf einen Fehler hinweist, ist die Ursache manchmal auf vorübergehende Bedingungen zurückzuführen. Eine Wiederherstellung ist dann möglich. Wenn ein Aufruf einer Methode der Play Billing Library einen BillingResponseCode-Wert zurückgibt, der auf einen behebbaren Fehler hinweist, solltest du den Aufruf wiederholen. In anderen Fällen gelten die Bedingungen nicht als vorübergehend und eine Wiederholung wird daher nicht empfohlen.

Vorübergehende Fehler erfordern unterschiedliche Wiederholungsstrategien, je nachdem, ob der Fehler während einer Sitzung auftritt, z. B. wenn ein Nutzer einen Kaufvorgang durchläuft, oder ob der Fehler im Hintergrund auftritt, z. B. wenn Sie die vorhandenen Käufe des Nutzers während onResume abfragen. Im Abschnitt Wiederholungsstrategien finden Sie Beispiele für diese verschiedenen Strategien. Im Abschnitt zu BillingResult-Antworten, die Sie wiederholen können, wird empfohlen, welche Strategie für den jeweiligen Antwortcode am besten geeignet ist.

Zusätzlich zum Antwortcode enthalten einige Fehlerantworten Nachrichten für die Fehlerbehebung und Protokollierung.

Wiederholungsstrategien

Einfache Wiederholung

Wenn der Nutzer gerade eine Sitzung hat, ist es besser, eine einfache Wiederholungsstrategie zu implementieren, damit der Fehler die Nutzererfahrung so wenig wie möglich beeinträchtigt. In diesem Fall empfehlen wir eine einfache Wiederholungsstrategie mit einer maximalen Anzahl von Versuchen als Abbruchbedingung.

Das folgende Beispiel zeigt eine einfache Wiederholungsstrategie zur Behandlung eines Fehlers beim Herstellen einer BillingClient-Verbindung:

// 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()
}
// ...

Wiederholung mit exponentiellem Backoff

Wir empfehlen, den exponentiellen Backoff für Vorgänge der Play Billing Library zu verwenden, die im Hintergrund ausgeführt werden und die Nutzerfreundlichkeit während der Sitzung nicht beeinträchtigen.

Es wäre beispielsweise sinnvoll, dies bei der Bestätigung neuer Käufe zu implementieren, da dieser Vorgang im Hintergrund ausgeführt werden kann und die Bestätigung bei einem Fehler nicht in Echtzeit erfolgen muss.

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-Antworten, die Sie wiederholen können

NETWORK_ERROR (Fehlercode 12)

Problem

Dieser Fehler weist darauf hin, dass ein Problem mit der Netzwerkverbindung zwischen dem Gerät und den Play-Systemen aufgetreten ist.

Mögliche Lösung

Verwenden Sie zur Wiederherstellung einfache Wiederholungsversuche oder einen exponentiellen Backoff, je nachdem, welche Aktion den Fehler ausgelöst hat.

SERVICE_TIMEOUT (Fehlercode -3)

Problem

Dieser Fehler weist darauf hin, dass die Anfrage das maximale Zeitlimit erreicht hat, bevor Google Play antworten konnte. Dies kann beispielsweise durch eine Verzögerung bei der Ausführung der Aktion verursacht werden, die durch den Aufruf der Play Billing Library angefordert wurde.

Mögliche Lösung

Dies ist in der Regel ein vorübergehendes Problem. Wiederholen Sie die Anfrage mit einer einfachen oder exponentiellen Backoff-Strategie, je nachdem, welche Aktion den Fehler zurückgegeben hat.

Im Gegensatz zu SERVICE_DISCONNECTED wird die Verbindung zum Google Play Billing-Dienst nicht getrennt. Du musst nur den versuchten Play Billing Library-Vorgang wiederholen.

SERVICE_DISCONNECTED (Fehlercode -1)

Problem

Dieser schwerwiegende Fehler weist darauf hin, dass die Verbindung der Client-App zum Google Play Store-Dienst über BillingClient getrennt wurde.

Mögliche Lösung

In Version 8.0.0 der Play Billing Library wurde die Funktion enableAutoServiceReconnection() eingeführt. Es wird dringend empfohlen, diese Funktion zu aktivieren, wenn Sie Ihre BillingClient erstellen. Dadurch kann die Bibliothek automatisch versuchen, die Verbindung wiederherzustellen, wenn ein Abrechnungs-API-Aufruf erfolgt, während der Dienst getrennt ist. Dadurch wird die Häufigkeit dieses Fehlers erheblich reduziert.

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();
Wenn Sie die automatische Wiederherstellung der Verbindung zum Dienst aktiviert haben

Die Play Billing Library versucht automatisch, die Verbindung wiederherzustellen. Wenn Sie beim Ausführen eines API-Aufrufs weiterhin den Antwortcode SERVICE_DISCONNECTED erhalten, bedeutet dies, dass die Bibliothek nach den automatischen Versuchen keine Verbindung wiederherstellen konnte. In diesem Szenario sollten Sie eine Wiederholungslogik in Ihrer App implementieren:

  • Für vom Nutzer initiierte Aktionen (in der Sitzung): Verwenden Sie einfache Wiederholungen des API-Aufrufs. Das zugrunde liegende Problem ist möglicherweise vorübergehend.
  • Für Hintergrundanfragen: Implementieren Sie Wiederholungsversuche mit exponentiellem Backoff, um eine Überlastung des Systems zu vermeiden, wenn die Verbindung länger unterbrochen ist.
Wenn Sie die automatische Wiederherstellung der Verbindung zu Diensten NICHT aktiviert haben

Um diesen Fehler so weit wie möglich zu vermeiden, solltest du immer die Verbindung zu den Google Play-Diensten prüfen, bevor du Aufrufe mit der Play Billing Library durchführst. Rufe dazu BillingClient.isReady auf.

Wenn Sie versuchen möchten, die Verbindung nach SERVICE_DISCONNECTED wiederherzustellen, sollte Ihre Clientanwendung versuchen, die Verbindung mit BillingClient.startConnection wiederherzustellen.

Verwenden Sie wie bei SERVICE_TIMEOUT einfache Wiederholungsversuche oder exponentiellen Backoff, je nachdem, welche Aktion den Fehler ausgelöst hat.

SERVICE_UNAVAILABLE (Fehlercode 2)

Wichtiger Hinweis:

Ab der Google Play Billing Library 6.0.0 wird SERVICE_UNAVAILABLE bei Netzwerkproblemen nicht mehr zurückgegeben. Er wird zurückgegeben, wenn der Abrechnungsdienst nicht verfügbar ist, und in den verworfenen SERVICE_TIMEOUT-Szenarien.

Problem

Dieser vorübergehende Fehler weist darauf hin, dass der Google Play Billing-Dienst derzeit nicht verfügbar ist. In den meisten Fällen bedeutet dies, dass ein Problem mit der Netzwerkverbindung zwischen dem Clientgerät und den Google Play Billing-Diensten vorliegt.

Mögliche Lösung

Dies ist in der Regel ein vorübergehendes Problem. Wiederholen Sie die Anfrage mit einer einfachen oder exponentiellen Backoff-Strategie, je nachdem, welche Aktion den Fehler zurückgegeben hat.

Im Gegensatz zu SERVICE_DISCONNECTED wird die Verbindung zum Google Play Billing-Dienst nicht getrennt und Sie müssen den versuchten Vorgang wiederholen.

BILLING_UNAVAILABLE (Fehlercode 3)

Problem

Dieser Fehler weist darauf hin, dass während des Kaufvorgangs ein Fehler bei der Nutzerabrechnung aufgetreten ist. Beispiele für solche Situationen:

  • Die Google Play Store App auf dem Gerät des Nutzers ist veraltet.
  • Der Nutzer befindet sich in einem nicht unterstützten Land.
  • Der Nutzer ist ein Unternehmensnutzer und der Administrator des Unternehmens hat Käufe durch Nutzer deaktiviert.
  • Google Play kann die Zahlungsmethode des Nutzers nicht belasten. Beispielsweise könnte die Kreditkarte des Nutzers abgelaufen sein.
  • Die Google Play Store App wird vom System blockiert, z. B. in einem vom OEM angepassten Kindermodus. In diesem Fall enthält die BillingResult die Debug-Nachricht Google Play Store is blocked.

Mögliche Lösung

  • Automatische Wiederholungsversuche sind in diesem Fall wahrscheinlich nicht hilfreich. Ein manueller Wiederholungsversuch kann jedoch hilfreich sein, wenn der Nutzer die Ursache des Problems behebt. Wenn der Nutzer beispielsweise seine Google Play Store-Version auf eine unterstützte Version aktualisiert, kann ein manueller Wiederholungsversuch des ursprünglichen Vorgangs funktionieren.

  • Wenn dieser Fehler auftritt, während der Nutzer nicht in der Sitzung ist, ist ein erneuter Versuch möglicherweise nicht sinnvoll. Wenn du im Rahmen des Kaufvorgangs einen BILLING_UNAVAILABLE-Fehler erhältst, hat der Nutzer während des Kaufvorgangs wahrscheinlich Feedback von Google Play erhalten und weiß möglicherweise, was schiefgelaufen ist. In diesem Fall könntest du eine Fehlermeldung anzeigen, die darauf hinweist, dass ein Fehler aufgetreten ist, und einen Button Noch einmal versuchen anbieten, damit der Nutzer die Möglichkeit hat, es manuell noch einmal zu versuchen, nachdem er das Problem behoben hat.

FEHLER (Fehlercode 6)

Problem

Dies ist ein schwerwiegender Fehler, der auf ein internes Problem mit Google Play selbst hinweist.

Mögliche Lösung

Manchmal sind interne Google Play-Probleme, die zu ERROR führen, vorübergehend. Zur Behebung kann ein Wiederholungsversuch mit exponentiellem Backoff implementiert werden. Wenn Nutzer sich in einer Sitzung befinden, ist ein einfacher Wiederholungsversuch vorzuziehen.

ITEM_ALREADY_OWNED

Problem

Diese Antwort gibt an, dass der Google Play-Nutzer das Abo oder Einmalkaufprodukt, das er kaufen möchte, bereits besitzt. In den meisten Fällen handelt es sich nicht um einen vorübergehenden Fehler, es sei denn, er wird durch einen veralteten Google Play-Cache verursacht.

Mögliche Lösung

Wenn die Ursache kein Cache-Problem ist, kannst du diesen Fehler vermeiden, indem du ein Produkt nicht zum Kauf anbietest, wenn der Nutzer es bereits besitzt. Prüfe die Berechtigungen des Nutzers, wenn du die zum Kauf verfügbaren Produkte anzeigst, und filtere die Produkte, die der Nutzer kaufen kann, entsprechend. Wenn die Client-App diesen Fehler aufgrund eines Cache-Problems erhält, wird der Cache von Google Play mit den neuesten Daten aus dem Play-Backend aktualisiert. In diesem Fall sollte der Fehler durch einen erneuten Versuch behoben werden. Rufe BillingClient.queryPurchasesAsync() auf, nachdem du einen ITEM_ALREADY_OWNED erhalten hast, um zu prüfen, ob der Nutzer das Produkt erworben hat. Wenn dies nicht der Fall ist, implementiere eine einfache Wiederholungslogik, um den Kauf noch einmal zu versuchen.

ITEM_NOT_OWNED

Problem

Diese Kaufantwort gibt an, dass der Google Play-Nutzer nicht der Inhaber des Abos oder einmaligen Kaufprodukts ist, das er ersetzen, bestätigen oder nutzen möchte. In den meisten Fällen handelt es sich hierbei nicht um einen vorübergehenden Fehler, es sei denn, er wird durch einen veralteten Cache von Google Play verursacht.

Mögliche Lösung

Wenn der Fehler aufgrund eines Cache-Problems auftritt, wird der Cache von Google Play mit den neuesten Daten aus dem Backend von Google Play aktualisiert. Eine Wiederholung mit einer einfachen Wiederholungsstrategie nach dem Fehler sollte diese spezifische vorübergehende Instanz beheben. Rufen Sie BillingClient.queryPurchasesAsync() auf, nachdem Sie ITEM_NOT_OWNED erhalten haben, um zu prüfen, ob der Nutzer das Produkt erworben hat. Wenn dies nicht der Fall ist, verwenden Sie eine einfache Wiederholungslogik, um den Kauf noch einmal zu versuchen.

Nicht wiederholbare BillingResult-Antworten

Diese Fehler können nicht mithilfe einer Wiederholungslogik behoben werden.

FEATURE_NOT_SUPPORTED

Problem

Dieser nicht wiederholbare Fehler weist darauf hin, dass Google Play Billing auf dem Gerät des Nutzers nicht unterstützt wird, wahrscheinlich aufgrund einer alten Google Play Store-Version.

Beispielsweise unterstützen die Geräte einiger Nutzer möglicherweise keine In-App-Nachrichten.

Mögliche Abhilfe

Verwende BillingClient.isFeatureSupported, um die Unterstützung von Funktionen zu prüfen, bevor du die Play Billing Library aufrufst.

when {
    billingClient.isReady -> {
        val billingResult =
            billingClient.isFeatureSupported(BillingClient.FeatureType.IN_APP_MESSAGING)
        if (billingResult.responseCode == BillingClient.BillingResponseCode.OK) {
            // use Feature
        }
    }
}

USER_CANCELED

Problem

Der Nutzer hat die Benutzeroberfläche für den Abrechnungsvorgang verlassen.

Mögliche Lösung

Dies dient nur zu Informationszwecken und kann ohne schwerwiegende Folgen fehlschlagen.

ITEM_UNAVAILABLE

Problem

Das Google Play Billing-Abo oder das einmalige Kaufprodukt ist für diesen Nutzer nicht verfügbar.

Mögliche Abhilfe

Achten Sie darauf, dass Ihre App die Produktdetails wie empfohlen mit queryProductDetailsAsync aktualisiert. Berücksichtige bei der Konfiguration in der Play Console, wie oft sich dein Produktkatalog ändert, um bei Bedarf zusätzliche Aktualisierungen zu implementieren. Versuche nur, Produkte über Google Play Billing zu verkaufen, die mit queryProductDetailsAsync die richtigen Informationen zurückgeben. Prüfen Sie die Konfiguration der Produktberechtigung auf Unstimmigkeiten. Beispielsweise fragen Sie möglicherweise ein Produkt ab, das nur für eine andere Region als die Region verfügbar ist, in der der Nutzer versucht, es zu kaufen. Damit ein Produkt gekauft werden kann, muss es aktiv und die zugehörige App veröffentlicht sein. Außerdem muss die App im Land des Nutzers verfügbar sein.

Manchmal, insbesondere während des Testens, ist in der Produktkonfiguration alles korrekt, aber Nutzer sehen diesen Fehler trotzdem. Dies kann auf eine Verzögerung bei der Weitergabe der Produktdetails auf den Google-Servern zurückzuführen sein. Versuche es später noch einmal.

DEVELOPER_ERROR

Problem

Dies ist ein schwerwiegender Fehler, der darauf hinweist, dass Sie eine API nicht ordnungsgemäß verwenden. Dieser Fehler kann beispielsweise auftreten, wenn Sie falsche Parameter für BillingClient.launchBillingFlow angeben.

Mögliche Lösung

Achten Sie darauf, dass Sie die verschiedenen Aufrufe der Play Billing Library richtig verwenden. Weitere Informationen zum Fehler finden Sie in der Debug-Meldung.