Google Play Billing Library in deine App integrieren

In diesem Thema wird beschrieben, wie Sie die Google Play Billing Library in Ihre App einbinden, um Produkte zu verkaufen.

Ablauf eines Kaufs

Hier sehen Sie einen typischen Kaufvorgang für einen Einmalkauf oder ein Abo.

1. Zeigen Sie den Nutzern, was sie kaufen können.
2. Starte den Kaufvorgang, damit der Nutzer den Kauf akzeptieren kann.
3. Bestätige den Kauf auf deinem Server.
4. Stellen Sie Nutzern Inhalte zur Verfügung.
5. Bestätige die Zustellung der Inhalte. Verbrauchen Sie bei Verbrauchsgütern den Kauf, damit der Nutzer den Artikel noch einmal kaufen kann.

Abos werden automatisch verlängert, bis sie gekündigt werden. Ein Abo kann folgende Status haben:

• Aktiv: Der Nutzer hat einen aktiven Status und Zugriff auf das Abo.
• Gekündigt: Der Nutzer hat gekündigt, hat aber bis zum Ablaufdatum weiterhin Zugriff.
• Kulanzzeitraum: Der Nutzer hat ein Zahlungsproblem, hat aber weiterhin Zugriff, während Google die Zahlungsmethode noch einmal versucht.
• In der Schwebe: Der Nutzer hat ein Zahlungsproblem und hat keinen Zugriff mehr, während Google die Zahlungsmethode noch einmal versucht.
• Pausiert: Der Nutzer hat seinen Zugriff pausiert und hat erst wieder Zugriff, wenn er die Pausierung aufhebt.
• Abgelaufen: Der Nutzer hat das Abo gekündigt und hat keinen Zugriff mehr darauf. Der Nutzer gilt nach Ablauf als Absteiger.

Verbindung zu Google Play initialisieren

Der erste Schritt zur Einbindung in das Abrechnungssystem von Google Play besteht darin, Ihrer App die Google Play Billing Library hinzuzufügen und eine Verbindung zu initialisieren.

Abhängigkeit von der Google Play Billing Library hinzufügen

Fügen Sie der build.gradle-Datei Ihrer App die Abhängigkeit „Google Play Billing Library“ hinzu, wie hier gezeigt:

dependencies {
    def billing_version = "7.1.1"

    implementation "com.android.billingclient:billing:$billing_version"
}

dependencies {
    val billing_version = "7.1.1"

    implementation("com.android.billingclient:billing:$billing_version")
}

Wenn Sie Kotlin verwenden, enthält das KTX-Modul der Google Play Billing Library Kotlin-Erweiterungen und Unterstützung für Tasks, mit denen Sie bei Verwendung der Google Play Billing Library idiomatischen Kotlin-Code schreiben können. Wenn Sie diese Erweiterungen in Ihr Projekt aufnehmen möchten, fügen Sie der Datei build.gradle Ihrer App die folgende Abhängigkeit hinzu:

dependencies {
    def billing_version = "7.1.1"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

dependencies {
    val billing_version = "7.1.1"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

BillingClient initialisieren

Nachdem Sie eine Abhängigkeit von der Google Play Billing Library hinzugefügt haben, müssen Sie eine BillingClient-Instanz initialisieren. BillingClient ist die Hauptschnittstelle für die Kommunikation zwischen der Google Play Billing Library und dem Rest Ihrer App. BillingClient bietet sowohl synchrone als auch asynchrone Methoden für viele gängige Abrechnungsvorgänge. Beachten Sie Folgendes:

• Wir empfehlen, jeweils nur eine aktive BillingClient-Verbindung offen zu haben, um mehrere PurchasesUpdatedListener-Callbacks für ein einzelnes Ereignis zu vermeiden.
• Es wird empfohlen, eine Verbindung für den BillingClient herzustellen, wenn Ihre App gestartet oder in den Vordergrund gebracht wird, damit Käufe zeitnah verarbeitet werden. Dazu können Sie ActivityLifecycleCallbacks verwenden, das von registerActivityLifecycleCallbacks registriert wurde, und auf onActivityResumed warten, um eine Verbindung zu initialisieren, wenn Sie zum ersten Mal feststellen, dass eine Aktivität fortgesetzt wird. Weitere Informationen dazu, warum diese Best Practice befolgt werden sollte, finden Sie im Abschnitt Käufe verarbeiten. Denken Sie auch daran, die Verbindung zu beenden, wenn Sie die App schließen.

Verwenden Sie newBuilder, um eine BillingClient zu erstellen. Sie können einen beliebigen Kontext an newBuilder() übergeben. BillingClient verwendet diesen dann, um einen Anwendungskontext abzurufen. Sie müssen sich also keine Sorgen um Speicherlecks machen. Wenn du Updates zu Käufen erhalten möchtest, musst du auch setListener aufrufen und dabei einen Verweis auf eine PurchasesUpdatedListener übergeben. Dieser Listener empfängt Updates für alle Käufe in Ihrer App.

private val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // To be implemented in a later section.
   }

private var billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   // Configure other settings.
   .build()

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // To be implemented in a later section.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    // Configure other settings.
    .build();

Mit Google Play verbinden

Nachdem Sie eine BillingClient erstellt haben, müssen Sie eine Verbindung zu Google Play herstellen.

Um eine Verbindung zu Google Play herzustellen, rufen Sie startConnection auf. Der Verbindungsaufbau ist asynchron. Du musst eine BillingClientStateListener implementieren, um einen Rückruf zu erhalten, sobald die Einrichtung des Clients abgeschlossen ist und er bereit ist, weitere Anfragen zu senden.

Sie müssen außerdem eine Wiederholungslogik implementieren, um den Verlust von Verbindungen zu Google Play zu verarbeiten. Wenn Sie die Wiederholungslogik implementieren möchten, überschreiben Sie die Rückrufmethode onBillingServiceDisconnected() und achten Sie darauf, dass BillingClient die Methode startConnection() aufruft, um eine neue Verbindung zu Google Play herzustellen, bevor weitere Anfragen gesendet werden.

Das folgende Beispiel zeigt, wie Sie eine Verbindung starten und testen, ob sie einsatzbereit ist:

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

billingClient.startConnection(new BillingClientStateListener() {
    @Override
    public void onBillingSetupFinished(BillingResult billingResult) {
        if (billingResult.getResponseCode() ==  BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    @Override
    public void onBillingServiceDisconnected() {
        // Try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
});

Zum Kauf verfügbare Produkte anzeigen

Nachdem Sie eine Verbindung zu Google Play hergestellt haben, können Sie nach Ihren verfügbaren Produkten suchen und sie Ihren Nutzern anzeigen.

Die Abfrage von Produktdetails ist ein wichtiger Schritt, bevor Ihre Produkte Nutzern präsentiert werden, da so lokalisierte Produktinformationen zurückgegeben werden. Achten Sie bei Abos darauf, dass Ihre Produktdarstellung allen Play-Richtlinien entspricht.

Wenn du In-App-Produktdetails abfragen möchtest, rufe queryProductDetailsAsync auf.

Um das Ergebnis des asynchronen Vorgangs zu verarbeiten, müssen Sie auch einen Listener angeben, der die Schnittstelle ProductDetailsResponseListener implementiert. Sie können dann onProductDetailsResponse überschreiben, wodurch der Listener benachrichtigt wird, wenn die Abfrage abgeschlossen ist, wie im folgenden Beispiel gezeigt:

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
    billingResult,
    productDetailsList ->
      // check billingResult
      // process returned productDetailsList
}

QueryProductDetailsParams queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            ImmutableList.of(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()))
        .build();

billingClient.queryProductDetailsAsync(
    queryProductDetailsParams,
    new ProductDetailsResponseListener() {
        public void onProductDetailsResponse(BillingResult billingResult,
                List<ProductDetails> productDetailsList) {
            // check billingResult
            // process returned productDetailsList
        }
    }
)

Wenn Sie Produktdetails abfragen, übergeben Sie eine Instanz von QueryProductDetailsParams, die eine Liste von Produkt-ID-Strings angibt, die in der Google Play Console erstellt wurden, zusammen mit einer ProductType. ProductType kann entweder ProductType.INAPP für Einmalkaufprodukte oder ProductType.SUBS für Abos sein.

Abfragen mit Kotlin-Erweiterungen

Wenn Sie Kotlin-Erweiterungen verwenden, können Sie In-App-Produktdetails abfragen, indem Sie die Erweiterungsfunktion queryProductDetails() aufrufen.

queryProductDetails() nutzt Kotlin-Coroutinen, sodass Sie keinen separaten Listener definieren müssen. Stattdessen wird die Funktion angehalten, bis die Abfrage abgeschlossen ist. Anschließend können Sie das Ergebnis verarbeiten:

suspend fun processPurchases() {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("product_id_example")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

In seltenen Fällen unterstützen einige Geräte ProductDetails und queryProductDetailsAsync() nicht. Das liegt in der Regel an veralteten Versionen der Google Play-Dienste. Im Leitfaden zur Migration zur Play Billing Library 5 erfahren Sie, wie Sie die Funktionen zur Abwärtskompatibilität verwenden, um für eine ordnungsgemäße Unterstützung dieses Szenarios zu sorgen.

Ergebnis verarbeiten

Die Google Play Billing Library speichert die Abfrageergebnisse in einer List von ProductDetails-Objekten. Sie können dann für jedes ProductDetails-Objekt in der Liste verschiedene Methoden aufrufen, um relevante Informationen zu einem In-App-Produkt aufzurufen, z. B. den Preis oder die Beschreibung. Eine Liste der verfügbaren Produktdetails findest du in der Liste der Methoden in der Klasse ProductDetails.

Bevor du einen Artikel zum Verkauf anbietest, solltest du prüfen, ob der Nutzer den Artikel bereits besitzt. Wenn der Nutzer einen Verbrauchsartikel hat, der sich noch in seiner Artikelbibliothek befindet, muss er ihn aufbrauchen, bevor er ihn noch einmal kaufen kann.

Bevor du ein Abo anbietest, solltest du prüfen, ob der Nutzer bereits ein Abo hat. Beachten Sie außerdem Folgendes:

• queryProductDetailsAsync() gibt Aboproduktdetails und maximal 50 Angebote pro Abo zurück.
• queryProductDetailsAsync() gibt nur Angebote zurück, für die der Nutzer infrage kommt. Wenn der Nutzer versucht, ein Angebot zu kaufen, für das er nicht infrage kommt (z. B. wenn in der App eine veraltete Liste der infrage kommenden Angebote angezeigt wird), wird er von Google Play darüber informiert, dass er nicht berechtigt ist. Er kann dann stattdessen das Basis-Abo kaufen.

Kaufvorgang starten

Wenn Sie eine Kaufanfrage von Ihrer App aus starten möchten, rufen Sie die Methode launchBillingFlow() aus dem Hauptthread Ihrer App auf. Diese Methode nimmt eine Referenz auf ein BillingFlowParams-Objekt an, das das relevante ProductDetails-Objekt enthält, das durch Aufrufen von queryProductDetailsAsync abgerufen wurde. Verwenden Sie die Klasse BillingFlowParams.Builder, um ein BillingFlowParams-Objekt zu erstellen.

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...;

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // For One-time products, "setOfferToken" method shouldn't be called.
        // For subscriptions, to get an offer token, call ProductDetails.subscriptionOfferDetails()
        // for a list of offers that are available to the user
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // For one-time products, "setOfferToken" method shouldn't be called.
            // For subscriptions, to get an offer token, call
            // ProductDetails.subscriptionOfferDetails() for a list of offers
            // that are available to the user.
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Die launchBillingFlow()-Methode gibt einen der in BillingClient.BillingResponseCode aufgeführten Antwortcodes zurück. Prüfen Sie dieses Ergebnis, um sicherzustellen, dass beim Starten des Kaufvorgangs keine Fehler aufgetreten sind. Ein BillingResponseCode von OK gibt an, dass die Einführung erfolgreich war.

Nach einem erfolgreichen Aufruf von launchBillingFlow() wird der Google Play-Kaufbildschirm angezeigt. Abbildung 1 zeigt einen Kaufbildschirm für ein Abo:

Google Play ruft onPurchasesUpdated() auf, um das Ergebnis des Kaufvorgangs an einen Listener zu senden, der die PurchasesUpdatedListener-Oberfläche implementiert. Der Listener wird mit der Methode setListener() angegeben, wenn du deinen Client initialisiert hast.

Sie müssen onPurchasesUpdated() implementieren, um mögliche Antwortcodes zu verarbeiten. Im folgenden Beispiel wird gezeigt, wie onPurchasesUpdated() überschrieben wird:

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
   if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
       for (purchase in purchases) {
           // Process the purchase as described in the next section.
       }
   } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
       // Handle an error caused by a user canceling the purchase flow.
   } else {
       // Handle any other error codes.
   }
}

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
    if (billingResult.getResponseCode() == BillingResponseCode.OK
        && purchases != null) {
        for (Purchase purchase : purchases) {
            // Process the purchase as described in the next section.
        }
    } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Nach einem erfolgreichen Kauf wird ein Google Play-Bestätigungsbildschirm angezeigt, der in etwa so aussieht wie in Abbildung 2.

Bei einem erfolgreichen Kauf wird außerdem ein Kauftoken generiert. Das ist eine eindeutige Kennung, die den Nutzer und die Produkt-ID des gekauften In-App-Produkts angibt. Das Kauftoken kann lokal in der App gespeichert werden. Wir empfehlen jedoch dringend, das Token an Ihren sicheren Back-End-Server zu senden, wo Sie den Kauf dann bestätigen und Betrug verhindern können. Dieser Vorgang wird unter Käufe erkennen und verarbeiten weiter beschrieben.

Der Nutzer erhält außerdem per E-Mail einen Beleg mit einer Bestell-ID oder einer eindeutigen Transaktions-ID. Nutzer erhalten eine E-Mail mit einer eindeutigen Bestell-ID für jeden einmaligen Produktkauf sowie für den ersten Abokauf und die nachfolgenden automatischen Verlängerungen. Sie können die Bestell-ID verwenden, um Erstattungen in der Google Play Console zu verwalten.

Personalisierten Preis angeben

Wenn Ihre App für Nutzer in der Europäischen Union verfügbar ist, müssen Sie beim Aufrufen von launchBillingFlow die Methode setIsOfferPersonalized() verwenden, um Nutzern mitzuteilen, dass der Preis eines Artikels mithilfe automatisierter Entscheidungsfindung personalisiert wurde.

Sie müssen Artikel 6 (1) (ea) CRD der Richtlinie zum Verbraucherrecht 2011/83/EU, um festzulegen, ob der von dir angebotene Preis personalisiert wurde.

setIsOfferPersonalized() nimmt eine boolesche Eingabe an. Wenn true, enthält die Google Play-Benutzeroberfläche die Offenlegung. Wenn false, wird die Offenlegung in der Benutzeroberfläche nicht angezeigt. Der Standardwert ist false.

Weitere Informationen finden Sie in der Hilfe für Verbraucher.

Nutzerkennungen anhängen

Wenn Sie den Kaufvorgang starten, kann Ihre App alle Nutzer-IDs, die Sie für den Nutzer haben, der den Kauf ausführt, mit obfuscatedAccountId oder obfuscatedProfileId verknüpfen. Eine Beispiel-ID könnte eine verschleierte Version der Anmeldung des Nutzers in Ihrem System sein. Wenn Sie diese Parameter festlegen, kann Google Betrug erkennen. Außerdem können Sie so dafür sorgen, dass Käufe dem richtigen Nutzer zugeordnet werden, wie im Abschnitt Berechtigungen für Nutzer gewähren beschrieben.

Käufe erkennen und verarbeiten

Die in diesem Abschnitt beschriebene Erkennung und Verarbeitung eines Kaufs gilt für alle Arten von Käufen, einschließlich Käufen außerhalb der App, z. B. für die Inanspruchnahme von Angeboten.

In Ihrer App werden neue Käufe und abgeschlossene ausstehende Käufe auf eine der folgenden Arten erkannt:

1. Wenn onPurchasesUpdated aufgerufen wird, weil Ihre App launchBillingFlow aufgerufen hat (wie im vorherigen Abschnitt beschrieben), oder wenn Ihre App mit einer aktiven Billing Library-Verbindung ausgeführt wird, wenn ein Kauf außerhalb Ihrer App erfolgt oder ein ausstehender Kauf abgeschlossen wird. Beispiel: Ein Familienmitglied genehmigt einen ausstehenden Kauf auf einem anderen Gerät.
2. Wenn Ihre App queryPurchasesAsync aufruft, um die Käufe des Nutzers abzufragen.

Bei 1 wird onPurchasesUpdated bei neuen oder abgeschlossenen Käufen automatisch aufgerufen, solange Ihre App ausgeführt wird und eine aktive Verbindung zur Google Play Billing Library besteht. Wenn Ihre Anwendung nicht ausgeführt wird oder keine aktive Verbindung zur Google Play Billing Library besteht, wird onPurchasesUpdated nicht aufgerufen. Denken Sie daran, dass Ihre App eine aktive Verbindung aufrechterhalten sollte, solange sie im Vordergrund geöffnet ist, damit sie zeitnah Kaufaktualisierungen erhält.

Für Punkt 2 müssen Sie BillingClient.queryPurchasesAsync() aufrufen, damit Ihre App alle Käufe verarbeitet. Wir empfehlen, dies zu tun, wenn Ihre App eine Verbindung zur Google Play Billing Library herstellt. Dies ist zu empfehlen, wenn Ihre App gestartet wird oder in den Vordergrund rückt, wie unter BillingClient initialisieren beschrieben. Rufen Sie dazu queryPurchasesAsync auf, wenn Sie ein erfolgreiches Ergebnis für onServiceConnected erhalten. Diese Empfehlung ist wichtig, um bei folgenden Ereignissen und Situationen richtig zu reagieren:

• Netzwerkprobleme während des Kaufs: Ein Nutzer kann einen Kauf abschließen und eine Bestätigung von Google erhalten, aber die Netzwerkverbindung seines Geräts wird unterbrochen, bevor sein Gerät und Ihre App über die PurchasesUpdatedListener eine Benachrichtigung über den Kauf erhalten.
• Mehrere Geräte: Ein Nutzer kauft einen Artikel auf einem Gerät und erwartet dann, dass er den Artikel auch sieht, wenn er das Gerät wechselt.
• Käufe außerhalb Ihrer App verarbeiten: Einige Käufe, z. B. die Inanspruchnahme von Angeboten, können außerhalb Ihrer App erfolgen.
• Übergang zum Kaufstatus verarbeiten: Ein Nutzer kann die Zahlung für einen ausstehenden Kauf abschließen, während Ihre Anwendung nicht ausgeführt wird. Er erwartet dann, dass er eine Bestätigung erhält, dass der Kauf abgeschlossen wurde, wenn er Ihre App öffnet.

Sobald Ihre App einen neuen oder abgeschlossenen Kauf erkennt, sollte sie Folgendes tun:

• Bestätigen Sie den Kauf.
• Gewähren Sie Nutzern Inhalte für abgeschlossene Käufe.
• Benachrichtigen Sie den Nutzer.
• Informieren Sie Google darüber, dass in Ihrer App abgeschlossene Käufe verarbeitet wurden.

Diese Schritte werden in den folgenden Abschnitten ausführlich beschrieben. Im letzten Abschnitt werden alle Schritte noch einmal zusammengefasst.

Kauf bestätigen

In Ihrer App sollten Käufe immer auf ihre Legitimität überprüft werden, bevor Nutzern Vorteile gewährt werden. Folge dazu der Anleitung unter Käufe vor der Gewährung von Berechtigungen prüfen. Erst nach der Überprüfung des Kaufs sollte Ihre App den Kauf verarbeiten und dem Nutzer Berechtigungen gewähren. Wie das geht, wird im nächsten Abschnitt erläutert.

Berechtigung für den Nutzer gewähren

Sobald Ihre App einen Kauf bestätigt hat, kann sie dem Nutzer weiterhin die Berechtigung gewähren und ihn benachrichtigen. Bevor Sie eine Berechtigung gewähren, muss in Ihrer App geprüft werden, ob der Kaufstatus PURCHASED ist. Wenn der Kauf den Status „AUSSTEHEND“ hat, sollte Ihre App den Nutzer darüber informieren, dass er noch Aktionen ausführen muss, um den Kauf abzuschließen, bevor die Berechtigung gewährt wird. Gewähre die Berechtigung nur, wenn der Kauf den Status „AUSSTEHEND“ in „ERFOLGREICH“ ändert. Weitere Informationen finden Sie unter Ausstehende Transaktionen verarbeiten.

Wenn Sie dem Kauf wie unter Nutzer-IDs an einen Kauf anhängen beschrieben Nutzer-IDs hinzugefügt haben, können Sie diese abrufen und dem richtigen Nutzer in Ihrem System zuordnen. Diese Methode ist nützlich, wenn Sie Käufe abgleichen müssen, bei denen in Ihrer App möglicherweise der Kontext verloren gegangen ist, für welchen Nutzer ein Kauf bestimmt ist. Hinweis: Für Käufe, die außerhalb Ihrer App getätigt werden, sind diese IDs nicht festgelegt. In diesem Fall kann Ihre App die Berechtigung entweder dem angemeldeten Nutzer gewähren oder den Nutzer auffordern, ein bevorzugtes Konto auszuwählen.

Nutzer benachrichtigen

Nachdem du dem Nutzer die Berechtigung erteilt hast, sollte deine App eine Benachrichtigung anzeigen, um den erfolgreichen Kauf zu bestätigen. So weiß der Nutzer, ob der Kauf erfolgreich war. Andernfalls könnte er die Nutzung Ihrer App beenden, sich an den Nutzersupport wenden oder sich in den sozialen Medien beschweren. Ihre App kann Kaufaktualisierungen jederzeit während des Anwendungslebenszyklus erkennen. Beispielsweise genehmigt ein Elternteil einen ausstehenden Kauf auf einem anderen Gerät. In diesem Fall kann Ihre App die Benachrichtigung des Nutzers zu einem geeigneten Zeitpunkt verzögern. Hier einige Beispiele, in denen eine Verzögerung angemessen wäre:

• Während des Actionparts eines Spiels oder in Zwischensequenzen kann eine Nachricht den Nutzer ablenken. In diesem Fall müssen Sie den Nutzer nach Abschluss des Aktionsteils benachrichtigen.
• Während der ersten Anleitung und der Nutzereinrichtung des Spiels Ein Nutzer hat beispielsweise einen Kauf außerhalb Ihrer App getätigt, bevor er sie installiert hat. Wir empfehlen Ihnen, neue Nutzer sofort nach dem Öffnen des Spiels oder während der Ersteinrichtung über die Prämie zu informieren. Wenn Nutzer in Ihrer App ein Konto erstellen oder sich anmelden müssen, bevor ihnen Berechtigungen gewährt werden, sollten Sie ihnen mitteilen, welche Schritte sie ausführen müssen, um ihren Kauf in Anspruch zu nehmen. Das ist wichtig, da Käufe nach 3 Tagen erstattet werden, wenn der Kauf in Ihrer App nicht verarbeitet wurde.

Für die Benachrichtigung des Nutzers über einen Kauf empfiehlt Google Play die folgenden Mechanismen:

• Ein In-App-Dialogfeld anzeigen
• Die Nachricht wird in einem In-App-Nachrichtenfeld angezeigt und es wird deutlich darauf hingewiesen, dass sich eine neue Nachricht im In-App-Nachrichtenfeld befindet.
• Verwenden Sie eine Betriebssystembenachrichtigung.

Die Benachrichtigung sollte den Nutzer über den erhaltenen Vorteil informieren. Beispiel: „Sie haben 100 Goldmünzen gekauft!“ Wenn der Kauf auf einem Vorteil eines Programms wie Play Pass beruht, muss der Nutzer dies in Ihrer App erfahren. Beispiel: „Artikel erhalten! Sie haben gerade 100 Edelsteine mit Play Pass erhalten. Weiter“. Für jedes Programm gibt es möglicherweise Empfehlungen dazu, welcher Text Nutzern angezeigt werden sollte, um die Vorteile zu kommunizieren.

Google über die Bearbeitung des Kaufs informieren

Nachdem Ihre App dem Nutzer die Berechtigung erteilt und ihn über die erfolgreiche Transaktion benachrichtigt hat, muss Ihre App Google darüber informieren, dass der Kauf erfolgreich verarbeitet wurde. Dazu müssen Sie den Kauf bestätigen. Dies muss innerhalb von drei Tagen geschehen, damit der Kauf nicht automatisch erstattet und die Berechtigung widerrufen wird. In den folgenden Abschnitten wird beschrieben, wie du verschiedene Arten von Käufen bestätigen kannst.

Verbrauchsprodukte

Wenn Ihre App ein sicheres Back-End hat, empfehlen wir für Verbrauchsmaterialien die Verwendung von Purchases.products:consume, um Käufe zuverlässig zu nutzen. Prüfe, ob der Kauf bereits verwendet wurde. Dazu musst du den Wert von consumptionState aus dem Ergebnis des Aufrufs von Purchases.products:get prüfen. Wenn Ihre App nur einen Client ohne Back-End hat, verwenden Sie consumeAsync() aus der Google Play Billing Library. Beide Methoden erfüllen die Bestätigungsanforderung und geben an, dass Ihre App dem Nutzer eine Berechtigung gewährt hat. Mit diesen Methoden kann Ihre App das einmalige Produkt, das dem eingegebenen Kauftoken entspricht, auch noch einmal zum Kauf anbieten. Bei consumeAsync() müssen Sie außerdem ein Objekt übergeben, das die ConsumeResponseListener-Schnittstelle implementiert. Dieses Objekt verarbeitet das Ergebnis des Verbrauchsvorgangs. Sie können die Methode onConsumeResponse() überschreiben, die von der Google Play Billing Library aufgerufen wird, wenn der Vorgang abgeschlossen ist.

Im folgenden Beispiel wird veranschaulicht, wie ein Produkt mit der Google Play Billing Library unter Verwendung des zugehörigen Kauftokens verwendet wird:

    val consumeParams =
        ConsumeParams.newBuilder()
            .setPurchaseToken(purchase.getPurchaseToken())
            .build()
    val consumeResult = withContext(Dispatchers.IO) {
        client.consumePurchase(consumeParams)
    }

    ConsumeParams consumeParams =
            ConsumeParams.newBuilder()
                .setPurchaseToken(purchase.getPurchaseToken())
                .build();

    ConsumeResponseListener listener = new ConsumeResponseListener() {
        @Override
        public void onConsumeResponse(BillingResult billingResult, String purchaseToken) {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        }
    };

    billingClient.consumeAsync(consumeParams, listener);

Nicht konsumierbare Produkte

Wenn Ihre App ein sicheres Back-End hat, empfehlen wir, Purchases.products:acknowledge zu verwenden, um Käufe zuverlässig zu bestätigen. Prüfe, ob der Kauf bereits bestätigt wurde. Dazu prüfe den Wert acknowledgementState im Ergebnis des Aufrufs von Purchases.products:get.

Wenn Ihre App nur für Kunden bestimmt ist, verwenden Sie BillingClient.acknowledgePurchase() aus der Google Play Billing Library in Ihrer App. Bevor ein Kauf bestätigt wird, sollte Ihre App mithilfe der Methode isAcknowledged() in der Google Play Billing Library prüfen, ob er bereits bestätigt wurde.

Im folgenden Beispiel wird gezeigt, wie ein Kauf mit der Google Play Billing Library bestätigt wird:

val client: BillingClient = ...
val acknowledgePurchaseResponseListener: AcknowledgePurchaseResponseListener = ...

val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
    .setPurchaseToken(purchase.purchaseToken)
val ackPurchaseResult = withContext(Dispatchers.IO) {
     client.acknowledgePurchase(acknowledgePurchaseParams.build())
}

BillingClient client = ...
AcknowledgePurchaseResponseListener acknowledgePurchaseResponseListener = ...

AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                    .setPurchaseToken(purchase.getPurchaseToken())
                    .build();
 client.acknowledgePurchase(acknowledgePurchaseParams, acknowledgePurchaseResponseListener);

Abos

Abos werden ähnlich wie nicht verbrauchbare Artikel behandelt. Verwenden Sie nach Möglichkeit Purchases.subscriptions.acknowledge aus der Google Play Developer API, um den Kauf über Ihr sicheres Backend zuverlässig zu bestätigen. Prüfe, ob der Kauf noch nicht bestätigt wurde. Dazu musst du die acknowledgementState in der Kaufressource von Purchases.subscriptions:get prüfen. Andernfalls kannst du ein Abo mit BillingClient.acknowledgePurchase() in der Google Play Billing Library bestätigen, nachdem du isAcknowledged() geprüft hast. Alle ersten Abokäufe müssen bestätigt werden. Aboverlängerungen müssen nicht bestätigt werden. Weitere Informationen dazu, wann Abos bestätigt werden müssen, finden Sie im Hilfeartikel Abos verkaufen.

Zusammenfassung

Das folgende Code-Snippet zeigt eine Zusammenfassung dieser Schritte.

fun handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify
.
    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

void handlePurchase(Purchase purchase) {
    // Purchase retrieved from BillingClient#queryPurchasesAsync or your
    // onPurchasesUpdated.
    Purchase purchase = ...;

    // Step 1: Send the purchase to your secure backend to verify the purchase
    // following
    // https://developer.android.com/google/play/billing/security#verify

    // Step 2: Update your entitlement storage with the purchase. If purchase is
    // in PENDING state then ensure the entitlement is marked as pending and the
    // user does not receive benefits yet. It is recommended that this step is
    // done on your secure backend and can combine in the API call to your
    // backend in step 1.

    // Step 3: Notify the user using appropriate messaging (delaying
    // notification if needed as discussed above).

    // Step 4: Notify Google the purchase was processed using the steps
    // discussed in the processing purchases section.
}

Wenn Sie prüfen möchten, ob diese Schritte in Ihrer App korrekt implementiert sind, folgen Sie dem Testleitfaden.

Ausstehende Transaktionen verarbeiten

Google Play unterstützt ausstehende Transaktionen, also Transaktionen, die einen oder mehrere zusätzliche Schritte erfordern, zwischen dem Zeitpunkt, an dem ein Nutzer einen Kauf auslöst, und dem Zeitpunkt, an dem die Zahlungsmethode für den Kauf verarbeitet wird. Ihre App sollte Nutzern erst dann die Berechtigung für diese Arten von Käufen gewähren, wenn Google Sie darüber informiert hat, dass die Zahlungsmethode des Nutzers erfolgreich belastet wurde.

Ein Nutzer kann beispielsweise eine Transaktion initiieren, indem er ein Geschäft auswählt, in dem er später bar bezahlt. Der Nutzer erhält einen Code sowohl per Benachrichtigung als auch per E-Mail. Wenn der Nutzer im Geschäft ankommt, kann er den Code an der Kasse einlösen und bar bezahlen. Google benachrichtigt dann sowohl Sie als auch den Nutzer darüber, dass die Zahlung eingegangen ist. Ihre App kann dem Nutzer dann eine Berechtigung gewähren.

Rufen Sie enablePendingPurchases() im Rahmen der Initialisierung von BillingClient auf, um ausstehende Transaktionen für Ihre App zu aktivieren. Ihre App muss ausstehende Transaktionen für Einmalkaufprodukte aktivieren und unterstützen. Bevor Sie Support hinzufügen, sollten Sie sich mit dem Kaufzyklus für ausstehende Transaktionen vertraut machen.

Wenn Ihre App einen neuen Kauf erhält, entweder über PurchasesUpdatedListener oder durch Aufrufen von queryPurchasesAsync, verwenden Sie die Methode getPurchaseState(), um zu ermitteln, ob der Kaufstatus PURCHASED oder PENDING ist. Sie sollten die Berechtigung nur gewähren, wenn der Status PURCHASED ist.

Wenn Ihre App ausgeführt wird und Sie eine aktive Play Billing Library-Verbindung haben, wenn der Nutzer den Kauf abschließt, wird PurchasesUpdatedListener noch einmal aufgerufen und PurchaseState ist jetzt PURCHASED. An diesem Punkt kann Ihre App den Kauf mit der Standardmethode für das Erkennen und Verarbeiten von Käufen verarbeiten. Ihre App sollte auch queryPurchasesAsync() in der onResume()-Methode Ihrer App aufrufen, um Käufe zu verarbeiten, die in den Status PURCHASED gewechselt sind, während Ihre App nicht aktiv war.

Wenn der Kauf von PENDING zu PURCHASED übergeht, erhält Ihr real_time_developer_notifications-Client eine ONE_TIME_PRODUCT_PURCHASED- oder SUBSCRIPTION_PURCHASED-Benachrichtigung. Wenn der Kauf storniert wird, erhalten Sie eine ONE_TIME_PRODUCT_CANCELED- oder SUBSCRIPTION_PENDING_PURCHASE_CANCELED-Benachrichtigung. Das kann passieren, wenn Ihr Kunde die Zahlung nicht innerhalb des erforderlichen Zeitraums abschließt. Sie können den aktuellen Status eines Kaufs jederzeit mit der Google Play Developer API prüfen.

Käufe in variabler Stückzahl verarbeiten

In den Versionen 4.0 und höher der Google Play Billing Library können Kunden bei Google Play mehrere In-App-Produkte in einer Transaktion kaufen, indem sie im Einkaufswagen eine Stückzahl angeben. Ihre App muss Käufe in mehreren Stückzahlen verarbeiten und Berechtigungen basierend auf der angegebenen Kaufmenge gewähren.

Damit Käufe mit mehreren Artikeln berücksichtigt werden, muss die Bereitstellungslogik Ihrer App eine Artikelmenge prüfen. Sie können über eine der folgenden APIs auf ein quantity-Feld zugreifen:

• getQuantity() aus der Google Play Billing Library.
• Purchases.products.quantity aus der Google Play Developer API

Nachdem Sie die Logik zum Bearbeiten von Käufen mit mehreren Stückzahlen hinzugefügt haben, müssen Sie die Funktion für die Stückzahl für das entsprechende Produkt auf der Seite zur Verwaltung von In-App-Produkten in der Google Play Console aktivieren.

Abrechnungskonfiguration des Nutzers abfragen

getBillingConfigAsync() gibt das Land an, das der Nutzer für Google Play verwendet.

Sie können die Abrechnungskonfiguration des Nutzers abfragen, nachdem Sie eine BillingClient erstellt haben. Im folgenden Code-Snippet wird beschrieben, wie ein Aufruf an getBillingConfigAsync() erfolgt. Verarbeiten Sie die Antwort, indem Sie BillingConfigResponseListener implementieren. Dieser Listener empfängt Updates für alle Abfragen zur Abrechnungskonfiguration, die von Ihrer App initiiert wurden.

Wenn die zurückgegebene BillingResult keine Fehler enthält, kannst du im Feld countryCode des BillingConfig-Objekts das Land des Nutzers in Google Play abrufen.

// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(getBillingConfigParams,
    object : BillingConfigResponseListener {
        override fun onBillingConfigResponse(
            billingResult: BillingResult,
            billingConfig: BillingConfig?
        ) {
            if (billingResult.responseCode == BillingResponseCode.OK
                && billingConfig != null) {
                val countryCode = billingConfig.countryCode
                ...
            } else {
                // TODO: Handle errors
            }
        }
    })

// Use the default GetBillingConfigParams.
GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(getBillingConfigParams,
    new BillingConfigResponseListener() {
      public void onBillingConfigResponse(
          BillingResult billingResult, BillingConfig billingConfig) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK
            && billingConfig != null) {
            String countryCode = billingConfig.getCountryCode();
            ...
         } else {
            // TODO: Handle errors
        }
      }
    });

Erinnerungen zum Einkaufswagen auf der Startseite von Google Play Spiele (standardmäßig aktiviert)

Entwickler von Spielen, die über In-App-Produkte Einnahmen erzielen, können Artikelnummern (SKUs), die in der Google Play Console aktiv sind, auch außerhalb ihrer App verkaufen. Eine Möglichkeit dazu ist die Funktion „Erinnerung an abgebrochene Einkäufe“, mit der Nutzer beim Stöbern im Google Play Store daran erinnert werden, zuvor abgebrochene Käufe abzuschließen. Diese Käufe erfolgen außerhalb Ihrer App, im Google Play Games-Dashboard im Google Play Store.

Diese Funktion ist standardmäßig aktiviert, damit Nutzer dort weitermachen können, wo sie aufgehört haben, und Entwickler ihre Umsätze steigern können. Sie können diese Funktion für Ihre App jedoch deaktivieren, indem Sie das Formular zum Deaktivieren der Erinnerungsfunktion an abgebrochene Einkäufe einreichen. Best Practices zum Verwalten von Artikelnummern in der Google Play Console finden Sie unter In-App-Produkt erstellen.

Die folgenden Bilder zeigen die Erinnerung an den Einkaufswagen im Google Play Store: