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 einbinden, um in Ihrer Anwendung eine alternative Abrechnung mit Auswahlmöglichkeit für Nutzer anzubieten.

Play Billing Library einrichten

Füge die Play Billing Library-Abhängigkeit zu deiner Android-App hinzu. Wenn du die APIs zur alternativen Abrechnung verwenden möchtest, benötigst du Version 5.2 oder höher. Wenn Sie von einer früheren Version migrieren müssen, folgen Sie der Migrationsanleitung, bevor Sie versuchen, die alternative Abrechnung zu implementieren.

Mit Google Play verbinden

Die ersten Schritte im Integrationsprozess sind mit denen im Integrationsleitfaden für Google Play Billing identisch. Es gibt aber einige Änderungen bei der Initialisierung des BillingClient:

• Sie müssen eine neue Methode aufrufen, um anzugeben, dass Sie dem Nutzer eine Auswahl an Abrechnungsoptionen anbieten möchten: enableUserChoiceBilling.
• Du musst eine UserChoiceBillingListener registrieren, wenn der Nutzer sich für eine alternative Abrechnung entschieden hat.

Das folgende Beispiel zeigt, wie ein BillingClient mit diesen Änderungen initialisiert wird:

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

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

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

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();

Nach dem Initialisieren von BillingClient 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 die gleiche Weise wie bei einer Einbindung des Abrechnungssystems von Google Play anzeigen. Wenn der Nutzer die zum Kauf verfügbaren Produkte gesehen und eines zum Kauf auswählt, starten Sie den Abrechnungsablauf mit Auswahlmöglichkeit für Nutzer wie im folgenden Abschnitt beschrieben.

Abrechnungsablauf mit Auswahlmöglichkeit für Nutzer starten

Starten Sie den Abrechnungsablauf mit Auswahlmöglichkeit für Nutzer, indem Sie launchBillingFlow() aufrufen. Dies funktioniert genauso wie das Starten eines Kaufvorgangs bei der Einbindung eines Google Play-Abrechnungssystems: Du stellst eine ProductDetails-Instanz und eine offerToken für das Produkt und das Angebot bereit, das der Nutzer in Anspruch nehmen 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 Google Play-Abrechnungssystem 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 des Nutzers (d.h. ein unterstütztes Land) unterstützt wird. Wenn das Google Play-Land des Nutzers unterstützt wird, prüft Google Play anhand der Konfiguration von BillingClient, ob eine alternative Abrechnung aktiviert wurde.
  • Wenn eine alternative Abrechnung mit Auswahlmöglichkeit für Nutzer aktiviert wurde, wird im Kaufvorgang die UX mit Auswahlmöglichkeit für Nutzer angezeigt.
  • Wenn die alternative Abrechnung mit Auswahlmöglichkeit für Nutzer nicht aktiviert ist, zeigt der Kaufvorgang die standardmäßige UX des Google Play-Abrechnungssystems ohne Auswahlmöglichkeit für Nutzer.
• Wenn das Google Play-Land des Nutzers kein unterstütztes Land ist, wird im Kaufvorgang die Standard-UX des Google Play-Abrechnungssystems ohne Auswahlmöglichkeit für Nutzer angezeigt.

Nutzerauswahl verarbeiten

Wie du den Rest des Kaufvorgangs abwickelst, 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 der Kaufvorgang im alternativen Abrechnungssystem gestartet werden muss. Insbesondere wird die Methode userSelectedAlternativeBilling() aufgerufen.

Das externe Transaktionstoken, das im UserChoiceDetails-Objekt angegeben ist, stellt eine Signatur dar, über die der Nutzer den alternativen Abrechnungsvorgang aufrufen kann. Verwenden Sie dieses Token, um alle Transaktionen zu melden, die sich aus dieser Auswahl ergeben. Weitere Informationen dazu finden Sie im Leitfaden zur Back-End-Integration.

Der UserChoiceBillingListener sollte die folgenden Aktionen ausführen:

• Rufe das oder die Produkte ab, die vom Nutzer gekauft werden, damit sie während des Kaufvorgangs im alternativen Abrechnungssystem angezeigt werden können.
• Erfassen Sie den als externes Transaktionstoken empfangenen String und senden Sie ihn an Ihr Back-End, um ihn zu speichern. Damit wird später die externe Transaktion an Google Play gemeldet, wenn der Nutzer diesen speziellen Kauf abschließt.
• Starten Sie den alternativen Kaufvorgang des Entwicklers.

Wenn der Nutzer den Kauf über das alternative Abrechnungssystem abschließt, musst du die Transaktion innerhalb von 24 Stunden an Google Play melden. Dazu musst du die Google Play Developer API über dein Back-End aufrufen. Gib dabei die externalTransactionToken und weitere Transaktionsdetails an. Weitere Informationen finden Sie in der Back-End-Integrationsanleitung.

Das folgende Beispiel zeigt, wie UserChoiceBillingListener implementiert wird:

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.
    }

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, fährt er mit dem Kauf über Google Play fort.

• Weitere Informationen zum Umgang mit neuen In-App-Käufen über das Abrechnungssystem von Google Play findest du unter Käufe verarbeiten im Leitfaden zur Einbindung der Bibliothek.
• Weitere Informationen zum Abokauf findest du unter Neue Abos im Leitfaden zur Aboverwaltung.

Änderungen im Abo verarbeiten

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

In diesem Abschnitt wird beschrieben, wie du mit einigen häufigen Szenarien bei Aboänderungen umgehst.

Upgrade- und Downgradeabläufe

Bei Aboänderungen, einschließlich Upgrade- und Downgradeabläufen, sollte je nachdem, ob das Abo ursprünglich über das Abrechnungssystem von Google Play oder ein alternatives Abrechnungssystem gekauft wurde, unterschiedlich gehandhabt werden.

Add-ons, die von einem vorhandenen Abo abhängen, dieselbe Zahlungsmethode verwenden und wiederkehrende Gebühren angleichen, werden als Upgrades behandelt. Bei anderen Add-ons sollten Nutzer das Abrechnungssystem auswählen können. Initiieren Sie mit launchBillingFlow() einen neuen Kauf, wie unter Abrechnungsvorgang mit Auswahlmöglichkeit für Nutzer starten beschrieben.

Abos, die über ein alternatives Abrechnungssystem gekauft wurden

Bei Abos, die ursprünglich nach Auswahl des Nutzers über das alternative Abrechnungssystem des Entwicklers erworben wurden, sollten Nutzer, die ein Upgrade oder Downgrade anfordern, das alternative Abrechnungssystem des Entwicklers verwenden, ohne die Auswahlmöglichkeit für Nutzer noch einmal zu durchlaufen.

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 mit der Nutzerauswahl wird nicht angezeigt, da die Auswahl des Nutzers für den ursprünglichen Kauf bei Upgrades und Downgrades beibehalten wird. Durch den Aufruf von launchBillingFlow() wird in diesem Fall ein neues externes Transaktionstoken für die Transaktion generiert, das Sie aus dem Callback abrufen können.

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

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

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

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

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

BillingFlowParams billingFlowParams =
        BillingFlowParams.newBuilder()
            .setProductDetailsParamsList(
                ImmutableList.of(
                    ProductDetailsParams.newBuilder()
                        // Fetched via 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 durch den vorherigen Aufruf für den Kauf des neuen Abos erhalten wurde.

Abos, die über das Abrechnungssystem von Google Play gekauft wurden

Ebenso sollten Nutzern, die ihr aktuelles Abo über das Abrechnungssystem von Google Play gekauft haben, nach der Auswahl des Nutzers der Upgrade- oder Downgrade-Vorgang im Abrechnungssystem von Google Play angezeigt werden. In der folgenden Anleitung wird beschrieben, wie du den Kaufvorgang für ein Upgrade oder Downgrade über das Abrechnungssystem von Google Play startest:

1. Ermitteln Sie die offerToken des ausgewählten Angebots für das neue Abo:

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

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

1. Sende die korrekten Informationen an das Abrechnungssystem von Google Play, um den neuen Kauf zu verarbeiten, einschließlich des Kauftokens für das vorhandene Abo:

val billingFlowParams =
    BillingFlowParams.newBuilder().setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                .setProductDetails(productDetailsNewPlan)
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOldPurchaseToken(oldToken)
            .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
            .build()
        )
        .build()

BillingClient.launchBillingFlow(activity, billingFlowParams)

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

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

Dieser Kauf wird im Abrechnungssystem von Google Play ausgeführt und deine App erhält den PurchasesUpdatedListener.onPurchaseUpdated-Aufruf mit dem Ergebnis des Kaufs. Wenn der Kauf erfolgreich war, empfängt auch die Methode onPurchaseUpdated() die neuen Kaufinformationen und Ihr Back-End empfängt eine Entwicklerbenachrichtigung in Echtzeit SUBSCRIPTION_PURCHASED. Beim Abrufen des Status für den neuen Kauf wird ein linkedPurchaseToken-Attribut mit dem alten Abokauf verknüpft, sodass du es wie empfohlen entfernen kannst.

Abokündigungen und ‐reaktivierungen

Nutzer sollten ihr Abo jederzeit kündigen können. Wenn ein Nutzer ein Abo kündigt, kann die Beendigung der Berechtigung bis zum Ende des Zahlungszeitraums aufgeschoben werden. Wenn ein Nutzer beispielsweise ein Monatsabo nach der Hälfte 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 noch technisch aktiv, sodass der Nutzer den Dienst verwenden kann.

Es ist nicht ungewöhnlich, dass Nutzer die Kündigung während dieses aktiven Zeitraums rückgängig machen. In dieser Anleitung wird dies als Wiederherstellung bezeichnet. In den folgenden Abschnitten wird beschrieben, wie Sie Wiederherstellungsszenarien in der Einbindung der alternativen Abrechnungs-API handhaben.

Abos, die über ein alternatives Abrechnungssystem gekauft wurden

Wenn Sie eine externe Transaktions-ID für ein gekündigtes Abo haben, müssen Sie launchBillingFlow() nicht aufrufen, um das Abo wiederherzustellen. Daher sollte sie für diese Art der Aktivierung nicht verwendet werden. Wenn ein Nutzer sein Abo reaktiviert, während er sich noch im aktiven Zeitraum eines gekündigten Abos befindet, findet zu diesem Zeitpunkt keine Transaktion statt. Sie können einfach weiterhin Verlängerungen melden, wenn der aktuelle Abrechnungszeitraum abgelaufen ist und die nächste Verlängerung erfolgt. Dazu gehören Fälle, in denen der Nutzer im Rahmen der Wiederherstellung ein Guthaben oder einen Sonderpreis für die Verlängerung erhält (z. B. eine Werbeaktion, mit der der Nutzer zur Fortsetzung seines Abos) ermutigt wird.

Abos, die über das Abrechnungssystem von Google Play gekauft wurden

Im Allgemeinen können Nutzer Abos im Abrechnungssystem von Google Play reaktivieren. Bei gekündigten Abos, die ursprünglich über das Abrechnungssystem von Google Play erworben wurden, kann der Nutzer die Kündigung rückgängig machen, solange das Abo über die Google Play-Funktion Wieder abonnieren aktiv war. In diesem Fall erhältst du in deinem Back-End eine SUBSCRIPTION_RESTARTED-Entwicklerbenachrichtigung in Echtzeit und es wird kein neues Kauftoken ausgegeben. Das ursprüngliche Token wird verwendet, um das Abo fortzusetzen. Informationen zum Verwalten der Wiederherstellung im Abrechnungssystem von Google Play findest du unter Wiederherstellungen im Leitfaden zur Aboverwaltung.

Sie können eine Wiederherstellung auch über die App im Abrechnungssystem von Google Play auslösen, indem Sie launchBillingFlow() aufrufen. Weitere Informationen dazu finden Sie unter Vor Ablauf des Abos – in-App. Für Nutzer, die den Ablauf der Nutzerauswahl für den ursprünglichen Kauf durchlaufen haben (der storniert wurde, aber noch aktiv ist), erkennt das System ihre Auswahl automatisch und zeigt die Benutzeroberfläche zum Wiederherstellen dieser Käufe an. Der Nutzer wird aufgefordert, den erneuten Kauf des Abos über Google Play zu bestätigen, muss den Vorgang zur Nutzerauswahl aber nicht noch einmal durchlaufen. In diesem Fall wird ein neues Kauftoken für den Nutzer ausgegeben. Ihr Backend erhält eine Entwicklerbenachrichtigung in Echtzeit SUBSCRIPTION_PURCHASED und der Wert linkedPurchaseToken für den neuen Kaufstatus wird wie bei einem Upgrade oder Downgrade auf das alte Kauftoken für das gekündigte Abo festgelegt.

Erneute Abos

Wenn ein Abo vollständig abläuft – sei es aufgrund einer Kündigung oder einer Ablehnung der Zahlung ohne Wiederherstellung (Kontosperre abgelaufen), muss der Nutzer das Abo neu abschließen, wenn er die Berechtigung neu aktivieren möchte.

Sie können das erneute Abonnieren auch über die App aktivieren, indem Sie diese ähnlich wie eine Standardregistrierung verarbeiten. Nutzer sollten das Abrechnungssystem auswählen können, das sie verwenden möchten. launchBillingFlow() kann in diesem Fall wie unter Abrechnungsablauf mit Auswahlmöglichkeit für Nutzer starten beschrieben aufgerufen werden.

Alternative Abrechnung testen

Lizenztester sollten zum Testen der Integration der alternativen Abrechnung verwendet werden. Transaktionen, die von Lizenztesterkonten initiiert wurden, werden nicht in Rechnung gestellt. Weitere Informationen zum Konfigurieren von Lizenztestern findest du unter In-App-Abrechnung mit App-Lizenzierung testen.

Nächste Schritte

Sobald Sie die In-App-Integration abgeschlossen haben, können Sie das Back-End einbinden.