Anleitung zur In-App-Integration externer Zahlungen

In diesem Dokument wird beschrieben, wie Sie die Play Billing Library APIs einbinden, um in berechtigten Apps externe Zahlungen anzubieten. Weitere Informationen zu diesem Programm finden Sie in den Programmanforderungen.

Play Billing Library einrichten

Fügen Sie Ihrer Android-App die Play Billing Library-Abhängigkeit hinzu. Wenn Sie die APIs für externe Zahlungen verwenden möchten, benötigen Sie Version 8.3 oder höher. Wenn Sie von einer älteren Version migrieren müssen, folgen Sie der Anleitung im Migrationsleitfaden, um ein Upgrade durchzuführen, bevor Sie mit der Einbindung beginnen.

Abrechnungsclient initialisieren

Die ersten Schritte im Einbindungsprozess sind dieselben wie im Leitfaden zur Einbindung von Google Play Billing. Es gibt jedoch einige Änderungen bei der Initialisierung von BillingClient:

Im folgenden Beispiel wird gezeigt, wie ein BillingClient mit diesen Änderungen initialisiert wird:

Kotlin

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

val developerProvidedBillingListener =
    DeveloperProvidedBillingListener { details ->
        // Handle user selection for developer provided billing option.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build()

Java

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

private DeveloperProvidedBillingListener developerProvidedBillingListener =
    new DeveloperProvidedBillingListener() {
        @Override
        public void onUserSelectedDeveloperBilling(
            DeveloperProvidedBillingDetails details) {
            // Handle user selection for developer provided billing option.
        }
    };

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableBillingProgram(
        EnableBillingProgramParams.newBuilder()
            .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
            .setDeveloperProvidedBillingListener(developerProvidedBillingListener)
            .build())
    .build();

Mit Google Play verbinden

Nachdem Sie den BillingClient initialisiert haben, stellen Sie eine Verbindung zu Google Play her, wie unter Mit Google Play verbinden beschrieben.

Berechtigung des Nutzers prüfen

Nachdem Sie eine Verbindung zu Google Play hergestellt haben, können Sie mit der Methode isBillingProgramAvailableAsync() prüfen, ob der Nutzer für das Programm für externe Zahlungen berechtigt ist. Wenn der Nutzer berechtigt ist, gibt diese Methode BillingResponseCode.OK zurück. Im folgenden Beispiel wird gezeigt, wie Sie die Berechtigung prüfen:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  object : BillingProgramAvailabilityListener {
    override fun onBillingProgramAvailabilityResponse(
      billingProgram: Int, billingResult: BillingResult) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return
        }

        // External payments are available. Can proceed with generating an
        // external transaction token.
})

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_PAYMENTS,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      int billingProgram, BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling external payments unavailable, etc.
            return;
        }

        // External payments are available. Can proceed with generating an external transaction token.
      }

    });

Im Abschnitt zur Antwortverarbeitung finden Sie weitere Informationen dazu, wie Ihre App auf andere Antwortcodes reagieren sollte. Wenn Sie Kotlin-Erweiterungen verwenden, können Sie Kotlin-Coroutinen nutzen, sodass Sie keinen separaten Listener definieren müssen.

Verfügbare Produkte anzeigen

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

Token für externe Transaktionen vorbereiten

Wenn Sie eine externe Transaktion an Google Play melden möchten, benötigen Sie ein Token für externe Transaktionen, das von der Play Billing Library generiert wurde. Jedes Mal, wenn der Nutzer über die API für externe Zahlungen eine externe Website oder App besucht, muss ein neues Token für externe Transaktionen generiert werden. Dazu können Sie die createBillingProgramReportingDetailsAsync API aufrufen. Das Token sollte unmittelbar vor dem Aufruf von launchBillingFlow generiert werden.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build()

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  object : BillingProgramReportingDetailsListener {
    override fun onCreateBillingProgramReportingDetailsResponse(
      billingResult: BillingResult,
      billingProgramReportingDetails: BillingProgramReportingDetails?) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            billingProgramReportingDetails?.externalTransactionToken
        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
    }
})

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .build();

billingClient.createBillingProgramReportingDetailsAsync(
  params,
  new BillingProgramReportingDetailsListener() {
    @Override
    public void onCreateBillingProgramReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable BillingProgramReportingDetails
        billingProgramReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          billingProgramReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to
        // the external website using DeveloperBillingOptionParams when
        // launchBillingFlow is called.
      }
});

Wenn Sie Kotlin-Erweiterungen verwenden, können Sie Kotlin-Coroutinen nutzen, sodass Sie keinen separaten Listener definieren müssen.

Ablauf für externe Zahlungen starten

Starten Sie den Ablauf für externe Zahlungen, indem Sie launchBillingFlow() aufrufen. Das ist ähnlich wie beim Starten eines Kaufvorgangs mit einer Einbindung des Abrechnungssystems von Google Play. Es wird jedoch ein zusätzlicher Parameter DeveloperBillingOptionParams angegeben, der angibt, dass Ihre App den Ablauf für externe Zahlungen für diesen Kauf aktivieren möchte.

DeveloperBillingOptionParams muss Folgendes enthalten:

Wenn Ihre App launchBillingFlow() mit DeveloperBillingOptionParams aufruft, 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 externe Zahlungen unterstützt werden (d.h. ein unterstütztes Land). Wenn das Google Play-Land des Nutzers unterstützt wird, prüft Google Play anhand der Konfiguration des BillingClient und der Angabe von DeveloperBillingOptionParams, ob externe Zahlungen aktiviert sind.
    • Wenn externe Zahlungen aktiviert sind, wird im Kaufvorgang die UX für die Nutzerauswahl angezeigt.
    • Wenn externe Zahlungen nicht aktiviert sind, wird im Kaufvorgang die Standard-UX des Abrechnungssystems von Google Play ohne Nutzerauswahl angezeigt.
  • Wenn das Google Play-Land des Nutzers kein unterstütztes Land ist, wird im Kaufvorgang die Standard-UX des Abrechnungssystems von Google Play ohne Nutzerauswahl angezeigt.

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

Das Google Play-Land des Nutzers ist kein unterstütztes Land.

Externe Zahlungen aktiviert (BillingClient-Einrichtung und launchBillingFlow)

Der Nutzer sieht die UX für die Nutzerauswahl.

Der Nutzer sieht die Standard-UX des Abrechnungssystems von Google Play.

Externe Zahlungen nicht aktiviert (entweder nicht bei der BillingClient-Einrichtung aktiviert oder DeveloperBillingOptionParams nicht an launchBillingFlow übergeben)

Der Nutzer sieht die Standard-UX des Abrechnungssystems von Google Play.

Der Nutzer sieht die Standard-UX des Abrechnungssystems von Google Play.

Das folgende Snippet zeigt, wie Sie DeveloperBillingOptionParams erstellen:

Kotlin

val developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build()

Java

DeveloperBillingOptionParams developerBillingOptionParams =
    DeveloperBillingOptionParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
        .setLinkUri(Uri.parse("https://www.example.com/external/purchase"))
        .setLaunchMode(
            DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
        .build();

Nutzerauswahl verarbeiten

Wie Sie den Rest des Kaufvorgangs verarbeiten, hängt davon ab, ob der Nutzer das Abrechnungssystem von Google Play oder die Zahlung auf Ihrer Website ausgewählt hat.

Wenn der Nutzer die Zahlung auf Ihrer Website oder in einer Zahlungs-App auswählt

Wenn der Nutzer die Zahlung auf Ihrer Website auswählt, ruft Google Play den DeveloperProvidedBillingListener auf, um die App darüber zu informieren, dass der Nutzer die Zahlung auf Ihrer Website oder in einer Zahlungs-App ausgewählt hat. Insbesondere wird die Methode onUserSelectedDeveloperBilling() aufgerufen.

Wenn Ihre App launchMode auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP setzt, startet Google Play den Link. Wenn launchMode auf CALLER_WILL_LAUNCH_LINK gesetzt wurde, ist Ihre App für das Starten des Links verantwortlich. Wenn Sie Nutzer zu einer Zahlungs-App weiterleiten, müssen Sie prüfen, ob der Nutzer die Zahlungs-App bereits auf seinem Gerät installiert hat.

Verwenden Sie dieses Token, um alle Transaktionen zu melden, die sich aus dieser Auswahl ergeben, wie in der Backend-Integrationsanleitung erläutert.

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 finden Sie im Leitfaden zur Einbindung der Play Billing Library unter Käufe verarbeiten.
  • Weitere Informationen zu Abokäufen finden Sie im Leitfaden zur Aboverwaltung unter Neue Abos.

Änderungen am Abo verarbeiten

Für Entwickler, die externe Zahlungen verwenden, müssen Käufe entweder über das Abrechnungssystem von Google Play verarbeitet oder mit einer externalTransactionId gemeldet werden, je nach Auswahl des Nutzers. Änderungen an bestehenden Abos, die über die Website des Entwicklers 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 Aboänderungen verarbeiten.

Abläufe für Upgrades und Downgrades

Änderungen an Aboplänen, einschließlich Abläufen für Upgrades und Downgrades, sollten unterschiedlich verarbeitet werden, je nachdem, ob das Abo ursprünglich über das Abrechnungssystem von Google Play oder über die Website des Entwicklers gekauft wurde.

Add-ons, die von einem bestehenden Abo abhängen, dieselbe Zahlungsmethode verwenden und wiederkehrende Gebühren haben, werden als Upgrades verarbeitet. 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 Ablauf für externe Zahlungen starten beschrieben.

Abos, die über die Website des Entwicklers oder eine Zahlungs-App gekauft wurden

Bei Abos, die ursprünglich über die Website des Entwicklers oder eine Zahlungs-App gekauft wurden, nachdem der Nutzer eine Auswahl getroffen hat, sollten Nutzer, die ein Upgrade oder Downgrade anfordern, über die Website des Entwicklers oder eine Zahlungs-App fortfahren, 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 andere Parameter im SubscriptionUpdateParams Objekt anzugeben, verwenden Sie setOriginalExternalTransactionId() und geben Sie die externe Transaktions ID für den ursprünglichen Kauf an.

DeveloperBillingOptionParams muss ebenfalls in diesem Aufruf angegeben werden. Der Bildschirm für die Nutzerauswahl wird nicht angezeigt, da die Nutzerauswahl für den ursprünglichen Kauf für Upgrades und Downgrades beibehalten wird. Sie müssen für diese Transaktion ein neues Token für externe Transaktionen generieren , wie hier beschrieben.

Wenn das Upgrade oder Downgrade über die Website des Entwicklers oder eine Zahlungs-App abgeschlossen ist, müssen Sie eine neue Transaktionmelden mit dem Token für externe Transaktionen melden, das Sie durch den vorherigen Aufruf für den neuen Abokauf erhalten haben.

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

Ebenso sollten Nutzer, die ihr aktuelles Abo über das Abrechnungssystem von Google Play gekauft haben, nachdem sie eine Nutzerauswahl getroffen haben, den Standardablauf von Google Play Billing durchlaufen. DeveloperBillingOptionParams darf im Aufruf von launchBillingFlow nicht festgelegt werden.

Abokündigungen und ‑wiederherstellungen

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 bezahlten Zeitraums aufgeschoben werden. Wenn ein Nutzer beispielsweise ein Monatsabo in der Mitte des Monats kündigt, kann er den Dienst möglicherweise noch etwa zwei Wochen lang nutzen, bis sein Zugriff entfernt wird. Während dieses Zeitraums ist das Abo technisch noch aktiv, sodass der Nutzer den Dienst nutzen kann.

Es kommt häufig vor, dass Nutzer während dieses aktiven Zeitraums die Kündigung rückgängig machen. In diesem Leitfaden wird dies als Wiederherstellung bezeichnet. In den folgenden Abschnitten wird beschrieben, wie Sie Wiederherstellungsszenarien in Ihrer API-Einbindung für externe Zahlungen verarbeiten.

Abos, die über die Website des Entwicklers gekauft wurden

Wenn Sie eine externe Transaktions-ID für ein gekündigtes Abo haben, ist es nicht erforderlich, launchBillingFlow() aufzurufen, um das Abo wiederherzustellen. Es sollte daher nicht für diese Art der Aktivierung verwendet werden. Wenn ein Nutzer sein Abo wiederherstellt, während der aktive Zeitraum eines gekündigten Abos noch läuft, erfolgt zu diesem Zeitpunkt keine Transaktion. Sie können einfach weiterhin Verlängerungen melden, wenn der aktuelle Zeitraum abläuft und die nächste Verlängerung erfolgt. Dazu gehören auch Fälle, in denen der Nutzer im Rahmen der Wiederherstellung eine Gutschrift oder einen Sonderpreis für die Verlängerung erhält (z. B. ein Angebot, um den Nutzer zu ermutigen, sein Abo fortzusetzen).

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

Im Allgemeinen können Nutzer Abos im Abrechnungssystem von Google Play wiederherstellen. Bei gekündigten Abos, die ursprünglich über das Abrechnungssystem von Google Play gekauft wurden, kann der Nutzer die Kündigung rückgängig machen, während das Abo über die Funktion „Abonnement reaktivieren“ von Google Play aktiv ist. In diesem Fall erhalten Sie in Ihrem Backend eine Echtzeit-Entwicklerbenachrichtigung SUBSCRIPTION_RESTARTED 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 finden Sie unter Vor Ablauf des Abos – In-App. Bei Nutzern, die den Nutzerauswahl-Ablauf für den ursprünglichen Kauf durchlaufen haben (der gekündigt, aber noch aktiv ist), erkennt das System ihre 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 aber den Ablauf für die Auswahlmöglichkeit für Nutzer nicht noch einmal durchlaufen. In diesem Fall wird für den Nutzer ein neues Kauf-Token ausgestellt. Ihr Backend erhält eine Echtzeit-Entwicklerbenachrichtigung SUBSCRIPTION_PURCHASED und der Wert von linkedPurchaseToken für den neuen Kaufstatus wird wie bei einem Upgrade oder Downgrade auf das alte Kauf-Token für das gekündigte Abo gesetzt.

Erneute Abos

Wenn ein Abo vollständig abläuft, sei es aufgrund einer Kündigung oder einer abgelehnten Zahlung ohne Wiederherstellung (abgelaufene Kontosperre), muss der Nutzer das Abo erneut abonnieren, wenn er die Berechtigung wiederherstellen möchte.

Das erneute Abonnieren kann auch über die App aktiviert werden, indem es ähnlich wie eine Standardanmeldung verarbeitet wird. Nutzer sollten auswählen können, welches Abrechnungssystem sie verwenden möchten. launchBillingFlow() kann in diesem Fall aufgerufen werden, wie unter Ablauf für externe Zahlungen starten beschrieben.

Antwortverarbeitung

Wenn ein Fehler auftritt, geben die Methoden isBillingProgramAvailableAsync() , createBillingProgramReportingDetailsAsync(), launchBillingFlow() möglicherweise einen anderen BillingResponseCode als BillingResponseCode.OK zurück. So sollten Sie mit diesen Antwortcodes umgehen:

  • BillingResponseCode.ERROR: Dies ist ein interner Fehler. Fahren Sie nicht mit der Transaktion fort und öffnen Sie nicht die externe Website. Wiederholen Sie den Vorgang, indem Sie die API noch einmal aufrufen.
  • BillingResponseCode.FEATURE_NOT_SUPPORTED: Die APIs für externe Zahlungen werden vom Google Play Store auf dem aktuellen Gerät nicht unterstützt. Fahren Sie nicht mit der Transaktion fort und öffnen Sie nicht die externe Website.
  • BillingResponseCode.DEVELOPER_ERROR: Es liegt ein Fehler in der Anfrage vor. Verwenden Sie die Debug-Meldung, um den Fehler zu identifizieren und zu beheben, bevor Sie fortfahren.
  • BillingResponseCode.USER_CANCELED: Öffnen Sie die externe Website oder App nicht. Rufen Sie launchBillingFlow() noch einmal auf, um dem Nutzer beim nächsten Versuch, ihn außerhalb der App weiterzuleiten, das Informationsdialogfeld anzuzeigen.
  • BillingResponseCode.BILLING_UNAVAILABLE: Die Transaktion ist nicht für externe Zahlungen berechtigt und daher ist die Abrechnung durch den Entwickler im Rahmen dieses Programms nicht verfügbar. Das liegt entweder daran, dass der Nutzer sich nicht in einem für dieses Programm berechtigten Land befindet oder dass Ihr Konto nicht erfolgreich für das Programm registriert wurde. Im letzteren Fall prüfen Sie den Registrierungsstatus in der Play Console.
  • BillingResponseCode.NETWORK_ERROR, BillingResponseCode.SERVICE_DISCONNECTED, BillingResponseCode.SERVICE_UNAVAILABLE: Dies sind vorübergehende Fehler, die mit einer geeigneten Richtlinie für Wiederholungsversuche verarbeitet werden sollten. Bei SERVICE_DISCONNECTED stellen Sie vor dem Wiederholen eine Verbindung zu Google Play her.

Links für externe Zahlungen testen

Lizenztester sollten verwendet werden, um Ihre Einbindung für externe Zahlungen zu testen. Transaktionen, die von Lizenztesterkonten initiiert wurden, werden Ihnen nicht in Rechnung gestellt. Weitere Informationen zum Konfigurieren von Lizenztestern finden Sie unter In-App-Abrechnung mit App-Lizenzierung testen.

Nächste Schritte

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