Anleitung zur In-App-Integration für die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer

In diesem Leitfaden wird beschrieben, wie Sie die APIs integrieren, um in Ihrer App eine alternative Abrechnung mit Wahlmöglichkeit für Nutzer anzubieten.

Einrichtung der Play Billing Library

Fügen Sie Ihrer Android-App die Play Billing Library-Abhängigkeit hinzu. Wenn Sie die alternativen Abrechnungs-APIs verwenden möchten, benötigen Sie Version 5.2 oder höher. Wenn Sie von einer früheren Version migrieren müssen, folgen Sie der Anleitung im Migrationsleitfaden, bevor Sie versuchen, die alternative Abrechnung zu implementieren.

Mit Google Play verbinden

Die ersten Schritte im Integrationsprozess sind dieselben wie im Integrationsleitfaden für Google Play Billing beschrieben. Es gibt jedoch einige Änderungen beim Initialisieren von BillingClient:

  • Sie müssen eine neue Methode aufrufen, um anzugeben, dass Sie dem Nutzer eine Auswahl an Abrechnungsoptionen anbieten möchten: enableUserChoiceBilling.
  • Sie müssen ein UserChoiceBillingListener registrieren, um Fälle zu verarbeiten, in denen der Nutzer die alternative Abrechnung auswählt.

Im folgenden Beispiel wird die Initialisierung eines BillingClient mit diesen Änderungen veranschaulicht:

Kotlin

val purchasesUpdatedListener =
   PurchasesUpdatedListener { billingResult, purchases ->
       // Handle new Google Play purchase.
   }

val userChoiceBillingListener =
   UserChoiceBillingListener { userChoiceDetails ->
       // Handle alternative billing choice.
   }

val billingClient = BillingClient.newBuilder(context)
   .setListener(purchasesUpdatedListener)
   .enablePendingPurchases()
   .enableUserChoiceBilling(userChoiceBillingListener)
   .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

Nachdem Sie BillingClient initialisiert haben, müssen Sie eine Verbindung zu Google Play herstellen, wie im Integrationsleitfaden beschrieben.

Verfügbare Produkte anzeigen

Sie können dem Nutzer verfügbare Produkte auf dieselbe Weise anzeigen wie bei einer Einbindung des Abrechnungssystems von Google Play. Wenn der Nutzer die zum Kauf verfügbaren Produkte gesehen und eines ausgewählt hat, starten Sie den Abrechnungsvorgang mit Auswahlmöglichkeit für Nutzer, wie im folgenden Abschnitt beschrieben.

Vorgang zur Abrechnung mit Auswahlmöglichkeit für Nutzer starten

Starten Sie den Vorgang zur Abrechnung mit Auswahlmöglichkeit für Nutzer, indem Sie launchBillingFlow() aufrufen. Das funktioniert genauso wie beim Starten eines Kaufvorgangs mit einer Integration des Google Play-Abrechnungssystems: Sie stellen eine ProductDetails-Instanz und eine offerToken bereit, die dem Produkt und dem Angebot entsprechen, das der Nutzer erwerben möchte. Wenn der Nutzer das Abrechnungssystem von Google Play auswählt, werden diese Informationen verwendet, um den Kaufvorgang fortzusetzen.

Wenn Entwickler launchBillingFlow() aufrufen, führt das Abrechnungssystem von Google Play die folgende Prüfung durch:

  • Das System prüft, ob das Google Play-Land des Nutzers ein Land ist, in dem die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer unterstützt wird (d.h. ein unterstütztes Land). Wenn das Google Play-Land des Nutzers unterstützt wird, prüft Google Play anhand der Konfiguration von BillingClient, ob die alternative Abrechnung aktiviert wurde.
    • Wenn die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer aktiviert wurde, wird im Kaufvorgang die Benutzeroberfläche für die Auswahlmöglichkeit für Nutzer angezeigt.
    • Wenn die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer nicht aktiviert ist, wird im Kaufvorgang die standardmäßige Benutzeroberfläche des Abrechnungssystems von Google Play ohne Auswahlmöglichkeit für Nutzer angezeigt.
  • Wenn das Google Play-Land des Nutzers kein unterstütztes Land ist, wird im Kaufvorgang die standardmäßige UX des Google Play-Abrechnungssystems ohne Auswahlmöglichkeit für Nutzer angezeigt.

Das Play-Land des Nutzers ist ein unterstütztes Land.

Das Play-Land des Nutzers wird nicht unterstützt

„enableUserChoiceBilling“ wird während der Einrichtung von „BillingClient“ aufgerufen

Nutzer sieht die Benutzeroberfläche für die Einwilligung

Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems

„enableUserChoiceBilling“ wurde bei der Einrichtung von „BillingClient“ nicht aufgerufen

Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems

Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems

Nutzerauswahl verarbeiten

Wie Sie den Rest des Kaufvorgangs abwickeln, hängt davon ab, ob der Nutzer das Abrechnungssystem von Google Play oder ein alternatives Abrechnungssystem ausgewählt hat.

Wenn der Nutzer ein alternatives Abrechnungssystem auswählt

Wenn der Nutzer das alternative Abrechnungssystem auswählt, ruft Google Play die UserChoiceBillingListener auf, um die App darüber zu informieren, dass sie den Kaufvorgang im alternativen Abrechnungssystem starten muss. Insbesondere wird die Methode userSelectedAlternativeBilling() aufgerufen.

Das im UserChoiceDetails-Objekt bereitgestellte externe Transaktions-Token stellt eine Signatur für die Entscheidung des Nutzers dar, den alternativen Abrechnungsablauf zu starten. Verwenden Sie dieses Token, um alle Transaktionen zu melden, die sich aus dieser Auswahl ergeben, wie im Leitfaden zur Backend-Integration beschrieben.

Das UserChoiceBillingListener sollte die folgenden Aktionen ausführen:

  • Rufen Sie das oder die Produkte ab, die der Nutzer kauft, damit sie im Kaufvorgang im alternativen Abrechnungssystem präsentiert werden können.
  • Erfassen Sie den String, der als externes Transaktionstoken empfangen wurde, und senden Sie ihn an Ihr Backend, um ihn zu speichern. Diese wird später verwendet, um die externe Transaktion bei Google Play zu melden, wenn der Nutzer diesen Kauf abschließt.
  • Starten Sie den alternativen Kaufvorgang des Entwicklers.

Wenn der Nutzer den Kauf über das alternative Abrechnungssystem abschließt, müssen Sie die Transaktion innerhalb von 24 Stunden an Google Play melden, indem Sie die Google Play Developer API von Ihrem Backend aus aufrufen und die externalTransactionToken sowie zusätzliche Transaktionsdetails angeben. Weitere Informationen finden Sie im Leitfaden zur Backend-Integration.

Das folgende Beispiel zeigt, wie Sie UserChoiceBillingListener implementieren:

Kotlin

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        devBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

Java

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Wenn der Nutzer das Abrechnungssystem von Google Play auswählt

Wenn der Nutzer das Abrechnungssystem von Google Play auswählt, wird der Kauf über Google Play fortgesetzt.

  • Weitere Informationen zum Verarbeiten neuer In-App-Käufe über das Abrechnungssystem von Google Play findest du im Integrationsleitfaden für die Bibliothek unter Käufe verarbeiten.
  • Weitere Informationen zum Kauf von Abos finden Sie im Leitfaden zur Aboverwaltung unter Neue Abos.

Änderungen am Abo verarbeiten

Bei Entwicklern, die die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer verwenden, müssen Käufe entweder über das Abrechnungssystem von Google Play abgewickelt oder mit einem externalTransactionId gemeldet werden, je nach Auswahl des Nutzers. Änderungen an bestehenden Abos, die über den Ablauf mit Auswahlmöglichkeit für Nutzer verarbeitet wurden, können bis zum Ablauf über dasselbe Abrechnungssystem vorgenommen werden.

In diesem Abschnitt wird beschrieben, wie Sie einige häufige Szenarien für Abänderungen von Abos behandeln.

Abläufe für Upgrades und Downgrades

Änderungen des Abomodells, einschließlich Upgrades und Downgrades, sollten unterschiedlich behandelt werden, je nachdem, ob das Abo ursprünglich über das Abrechnungssystem von Google Play oder über ein alternatives Abrechnungssystem gekauft wurde.

Add-ons, die von einem bestehenden Abo abhängen, dieselbe Zahlungsmethode verwenden und bei denen wiederkehrende Gebühren angeglichen werden, werden als Upgrades behandelt. Bei anderen Add-ons sollten Nutzer auswählen können, welches Abrechnungssystem sie verwenden möchten. Starten Sie einen neuen Kaufvorgang mit launchBillingFlow(), wie unter Abrechnungsvorgang mit Auswahlmöglichkeit für Nutzer starten beschrieben.

Über ein alternatives Abrechnungssystem gekaufte Abos

Bei Abos, die ursprünglich über das alternative Abrechnungssystem des Entwicklers nach der Auswahlmöglichkeit für Nutzer gekauft wurden, sollten Nutzer, die ein Upgrade oder Downgrade anfordern, das alternative Abrechnungssystem des Entwicklers nutzen, ohne die Auswahlmöglichkeit für Nutzer noch einmal durchlaufen zu müssen.

Rufen Sie dazu launchBillingFlow() auf, wenn der Nutzer ein Upgrade oder Downgrade anfordert. Anstatt ein SubscriptionUpdateParams-Objekt in den Parametern anzugeben, verwenden Sie setOriginalExternalTransactionId und geben Sie die externe Transaktions-ID für den ursprünglichen Kauf an. Der Bildschirm für die Nutzerauswahl wird in diesem Fall nicht angezeigt, da die Nutzerauswahl für den ursprünglichen Kauf bei Upgrades und Downgrades beibehalten wird. Der Aufruf von launchBillingFlow() generiert in diesem Fall ein neues externes Transaktionstoken für die Transaktion, das Sie über den Callback abrufen können.

Kotlin

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = //... ;

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
        )
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Java

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync.
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build()
            )
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Wenn das Upgrade oder Downgrade im alternativen Abrechnungssystem abgeschlossen ist, müssen Sie eine neue Transaktion melden. Verwenden Sie dazu das externe Transaktionstoken, das Sie durch den vorherigen Aufruf für den Kauf des neuen Abos erhalten haben.

Über das Abrechnungssystem von Google Play gekaufte Abos

Nutzer, die ihr aktuelles Abo nach der Einführung der Auswahlmöglichkeit für Nutzer über das Abrechnungssystem von Google Play gekauft haben, sollten ebenfalls den Ablauf zum Upgraden oder Downgraden im Abrechnungssystem von Google Play sehen. In der folgenden Anleitung wird beschrieben, wie Sie den Kaufvorgang für ein Upgrade oder Downgrade über das Abrechnungssystem von Google Play starten:

  1. Ermitteln Sie die offerToken des ausgewählten Angebots für den neuen Plan:

    Kotlin

    val offerTokenNewPlan = productDetailsNewPlan
     .getSubscriptionOfferDetails(selectedOfferIndex)
     .getOfferToken()

    Java

    String offerTokenNewPlan = productDetailsNewPlan
        .getSubscriptionOfferDetails(selectedOfferIndex)
        .getOfferToken();

  2. Senden Sie die richtigen Informationen an das Abrechnungssystem von Google Play, um den neuen Kauf zu verarbeiten, einschließlich des Kauf-Tokens für das bestehende Abo:

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

    BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
            )
        )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Dieser Kauf wird über das Abrechnungssystem von Google Play abgewickelt und Ihre App erhält den PurchasesUpdatedListener.onPurchaseUpdated-Aufruf mit dem Ergebnis des Kaufs. Wenn der Kauf erfolgreich war, erhält die onPurchaseUpdated()-Methode auch die neuen Kaufinformationen und Ihr Backend erhält eine SUBSCRIPTION_PURCHASED-Entwicklerbenachrichtigung in Echtzeit. Beim Abrufen des Status für den neuen Kauf verweist ein linkedPurchaseToken-Attribut auf den alten Abo-Kauf, sodass Sie ihn wie empfohlen einstellen können.

Abo-Kündigungen und ‑Wiederherstellungen

Nutzer sollten ihr Abo jederzeit kündigen können. Wenn ein Nutzer ein Abo kündigt, kann die Beendigung des Anspruchs bis zum Ende des bezahlten Zeitraums aufgeschoben werden. Wenn ein Nutzer beispielsweise ein Monatsabo in der Mitte des Monats kündigt, kann er noch etwa zwei Wochen lang auf den Dienst zugreifen, bis sein Zugriff entfernt wird. Während dieses Zeitraums ist das Abo technisch gesehen noch aktiv, sodass der Nutzer den Dienst weiterhin nutzen kann.

Es ist nicht ungewöhnlich, dass Nutzer sich während dieses aktiven Zeitraums entscheiden, die Kündigung rückgängig zu machen. In diesem Leitfaden wird dies als Wiederherstellung bezeichnet. In den folgenden Abschnitten wird beschrieben, wie Sie Wiederherstellungsszenarien in Ihrer alternativen Abrechnungs-API-Integration behandeln.

Über ein alternatives Abrechnungssystem gekaufte Abos

Wenn Sie eine externe Transaktions-ID für ein gekündigtes Abo haben, ist es nicht erforderlich, launchBillingFlow() aufzurufen, um das Abo wiederherzustellen. Diese Methode sollte also nicht für diese Art der Aktivierung verwendet werden. Wenn ein Nutzer sein Abo wiederherstellt, während das gekündigte Abo noch aktiv ist, findet zu diesem Zeitpunkt keine Transaktion statt. Sie können einfach weiterhin Verlängerungen melden, wenn der aktuelle Zyklus abläuft und die nächste Verlängerung erfolgt. Das gilt auch, wenn der Nutzer im Rahmen der Wiederherstellung eine Gutschrift oder einen Sonderpreis für die Verlängerung erhält, z. B. im Rahmen einer Werbeaktion, um ihn zur Fortsetzung des Abos zu motivieren.

Über das Abrechnungssystem von Google Play gekaufte Abos

Im Allgemeinen können Nutzer Abos über das Abrechnungssystem von Google Play reaktivieren. Bei gekündigten Abos, die ursprünglich über das Abrechnungssystem von Google Play gekauft wurden, kann der Nutzer die Kündigung über die Funktion Nochmal abonnieren von Google Play rückgängig machen, solange das Abo aktiv ist. In diesem Fall erhalten Sie in Ihrem Backend eine SUBSCRIPTION_RESTARTED-Entwicklerbenachrichtigung in Echtzeit und es wird kein neues Kauf-Token ausgestellt. Das ursprüngliche Token wird verwendet, um das Abo fortzusetzen. Informationen zum Verwalten der Wiederherstellung im Abrechnungssystem von Google Play finden Sie im Leitfaden zur Aboverwaltung unter Wiederherstellungen.

Sie können auch eine Wiederherstellung im Abrechnungssystem von Google Play über die App auslösen, indem Sie launchBillingFlow() aufrufen. Eine Anleitung dazu findest du unter Vor Ablauf des Abos – In-App. Bei Nutzern, die den Ablauf zur Nutzerauswahl für den ursprünglichen Kauf durchlaufen haben (der storniert wurde, aber weiterhin aktiv ist), erkennt das System die Auswahl automatisch und zeigt die Benutzeroberfläche zum Wiederherstellen dieser Käufe an. Sie werden aufgefordert, den erneuten Kauf des Abos über Google Play zu bestätigen, müssen den Ablauf zur Nutzerauswahl aber nicht noch einmal durchlaufen. In diesem Fall wird für den Nutzer ein neues Kauf-Token ausgestellt. Ihr Backend erhält eine SUBSCRIPTION_PURCHASED-Entwicklerbenachrichtigung in Echtzeit und der linkedPurchaseToken-Wert für den neuen Kaufstatus wird wie bei einem Upgrade oder Downgrade festgelegt. Dabei wird das alte Kauf-Token für das Abo verwendet, das gekündigt wurde.

Abo erneuern

Wenn ein Abo vollständig abläuft, sei es aufgrund einer Kündigung oder eines Zahlungsablehnung ohne Wiederherstellung (eine abgelaufene Kontosperre), muss der Nutzer ein neues Abo abschließen, wenn er die Berechtigung wieder aktivieren möchte.

Die erneute Anmeldung kann auch über die App erfolgen. Die Verarbeitung erfolgt dabei ähnlich wie bei einer Standardregistrierung. Nutzer sollten auswählen können, welches Abrechnungssystem sie verwenden möchten. In diesem Fall kann launchBillingFlow() aufgerufen werden, wie unter Abrechnungsvorgang mit Auswahlmöglichkeit für Nutzer starten beschrieben.

Alternative Abrechnung testen

Lizenztester sollten verwendet werden, um Ihre Integration der alternativen Abrechnung zu testen. Für Transaktionen, die von Konten von Lizenztestern initiiert wurden, erhalten Sie keine Rechnung. Weitere Informationen zum Konfigurieren von Lizenztestern finden Sie unter In-App-Abrechnung mit App-Lizenzierung testen.

Nächste Schritte

Nachdem Sie die In-App-Integration abgeschlossen haben, können Sie Ihr Backend einbinden.