In-App-Integrationsanleitung nur für die alternative Abrechnung

Hinweis :Das manuelle Melden nur für die alternative Abrechnung wird eingestellt. Weitere Informationen zu Migrationsfristen finden Sie hier. Weitere Informationen dazu, welche Transaktionen und wie Sie migriert werden müssen, finden Sie unter Von manueller Berichterstellung migrieren.

In diesem Leitfaden wird beschrieben, wie du die APIs einbindest, um nur in berechtigten Anwendungen eine alternative Abrechnung (d.h. ohne Auswahlmöglichkeit für Nutzer) anzubieten. Weitere Informationen zu diesen Programmen, einschließlich der Teilnahmevoraussetzungen und des geografischen Geltungsbereichs, finden Sie unter Alternative Abrechnung.

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 6.1 oder höher.

Mit Google Play verbinden

Hinweis :Wenn du nur die alternative Abrechnung verwendest, muss deine App keine PurchasesUpdatedListener zur Verfügung stellen, die zum Abhören von Transaktionen über das Abrechnungssystem von Google Play verwendet wird.

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 Ihre App nur ein alternatives Abrechnungssystem verwendet: enableAlternativeBillingOnly.

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

Kotlin

var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build();

Nach dem Initialisieren von BillingClient müssen Sie eine Verbindung zu Google Play herstellen, wie im Integrationsleitfaden beschrieben.

Verfügbarkeit wird geprüft

Hinweis: Eine Anleitung zum Beheben von Fehlern aus dieser API finden Sie im Abschnitt zum Umgang mit Antworten.

In deiner App sollte durch Aufrufen von isAlternativeBillingOnlyAvailableAsync bestätigt werden, dass nur die alternative Abrechnung verfügbar ist.

Diese API gibt BillingResponseCode.OK zurück, wenn nur eine alternative Abrechnung verfügbar ist. Weitere Informationen dazu, wie Ihre Anwendung auf andere Antwortcodes reagieren sollte, finden Sie unter Umgang mit Antworten.

Kotlin

billingClient.isAlternativeBillingOnlyAvailableAsync(object:
    AlternativeBillingOnlyAvailabilityListener {
        override fun onAlternativeBillingOnlyAvailabilityResponse(
            billingResult: BillingResult) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors,
                // handling alternative billing only being unavailable, etc.
                return
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Java

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

Informationsdialogfeld für Nutzer

Hinweis: Eine Anleitung zum Umgang mit Fehlern aus dieser API finden Sie im Abschnitt „Umgang mit Antworten“.

Hinweis: Wenn Sie eine alternative Abrechnung nur über APIs zur alternativen Abrechnung anbieten, werden die Anforderungen an die Nutzerfreundlichkeit durch die Einbindung in die clientseitigen APIs und deren Verwendung erfüllt. Die vorläufigen Anforderungen zur Nutzererfahrung musst du nicht separat beachten.

Wenn du nur die alternative Abrechnung einbinden möchtest, muss in deiner zulässigen App ein Informationsbildschirm angezeigt werden, aus dem hervorgeht, dass die Abrechnung nicht von Google Play verwaltet wird. Der Bildschirm mit den Informationen muss Nutzern durch Aufrufen der showAlternativeBillingOnlyInformationDialog API angezeigt werden, bevor der Vorgang für die alternative Abrechnung jedes Mal gestartet wird. Wenn der Nutzer das Dialogfeld bereits bestätigt hat, führt die Verwendung dieser API normalerweise nicht dazu, dass das Dialogfeld wieder angezeigt wird. Es kann vorkommen, dass einem Nutzer das Dialogfeld noch einmal angezeigt wird, z. B. wenn er Caches auf seinem Gerät löscht.

Kotlin

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity : Activity = ...;

val listener : AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { 
        override fun onAlternativeBillingOnlyInformationDialogResponse(
            billingResult: BillingResult) {
            // check billingResult
        }
}

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener)

Java

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

BillingResult billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(activity,
        listener);

Wenn diese Methode BillingResponseCode.OK zurückgibt, kann Ihre Anwendung mit der Transaktion fortfahren. Im Fall von BillingResponseCode.USER_CANCELED sollte Ihre Anwendung showAlternativeBillingOnlyInformationDialog aufrufen, um das Dialogfeld wieder für den Nutzer anzuzeigen. Weitere Antwortcodes finden Sie im Abschnitt Umgang mit Antworten.

Transaktionen an Google Play melden

Hinweis: Eine Anleitung zum Umgang mit Fehlern aus dieser API finden Sie unter „Antwortbehandlung“.

Alle Transaktionen, die über ein alternatives Abrechnungssystem ausgeführt werden, müssen Google Play gemeldet werden. Rufen Sie dazu innerhalb von 24 Stunden die Google Play Developer API aus Ihrem Back-End auf und stellen Sie eine externalTransactionToken bereit, die über die unten beschriebene API abgerufen wird. Für jeden einmaligen Kauf, jedes neue Abo sowie für alle Upgrades/Downgrades eines vorhandenen Abos sollte ein neues externalTransactionToken generiert werden. Informationen zum Melden einer Transaktion nach Erhalt eines externalTransactionToken finden Sie im Leitfaden zur Back-End-Integration.

Kotlin

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object:
    AlternativeBillingOnlyReportingDetailsListener {
        override fun onAlternativeBillingOnlyTokenResponse(
            billingResult: BillingResult,
            alternativeBillingOnlyReportingDetails:
                AlternativeBillingOnlyReportingDetails?) {
            if (billingResult.responseCode !=  BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return
            }

            val externalTransactionToken =
                alternativeBillingOnlyReportingDetails?
                    .externalTransactionToken

            // Send transaction token to backend and report to Google Play.
        }
    });

Java

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

Umgang mit Antworten

Die oben genannten Methoden isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() und createAlternativeBillingOnlyReportingDetailsAsync() geben im Fall von Fehlern möglicherweise andere Antworten als BillingResponseCode.OK zurück. Im Folgenden wird die empfohlene Behandlung der Fehler beschrieben:

• ERROR: Das ist ein interner Fehler. Fahre mit der Verarbeitung der Transaktion über das alternative Abrechnungssystem fort. Die Transaktion muss Google nicht gemeldet werden, auch nicht für Verlängerungen betroffener Abos.
• FEATURE_NOT_SUPPORTED: Die APIs zur alternativen Abrechnung werden vom Play Store auf dem aktuellen Gerät nicht unterstützt. Fahren Sie mit der Verarbeitung der Transaktion über das alternative Abrechnungssystem fort. Die Transaktion muss Google nicht gemeldet werden. Dasselbe gilt für Verlängerungen von betroffenen Abos.
• USER_CANCELED: Rufe showAlternativeBillingOnlyInformationDialog() noch einmal auf, damit dem Nutzer das Dialogfeld mit Informationen angezeigt wird, wenn er das nächste Mal versucht, einen Kauf zu tätigen.
• BILLING_UNAVAILABLE: Die Transaktion kommt nur für die alternative Abrechnung infrage und sollte daher im Rahmen dieses Programms nicht fortgesetzt werden. Der Nutzer befindet sich entweder in einem Land, in dem er nicht für dieses Programm berechtigt ist, oder dass sich dein Konto nicht erfolgreich für das Programm angemeldet hat. Sollte dies der Fall sein, prüfe deinen Anmeldestatus in der Play Console.
• DEVELOPER_ERROR: Bei der Anfrage ist ein Fehler aufgetreten. Verwenden Sie die Debug-Meldung, um den Fehler zu identifizieren und zu beheben, bevor Sie fortfahren.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Dies sind vorübergehende Fehler, die wiederholt werden sollten. Stellen Sie im Fall von SERVICE_DISCONNECTED wieder eine Verbindung mit Google Play her, bevor Sie es noch einmal versuchen.

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.