In diesem Dokument wird beschrieben, wie Sie die APIs der Play Billing Library einbinden, um in berechtigten Apps externe Zahlungen anzubieten. Weitere Informationen zu diesem Programm
Einrichtung der Play Billing Library
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 früheren Version migrieren müssen, folgen Sie der Anleitung im Migrationsleitfaden, um ein Upgrade durchzuführen, bevor Sie mit der Integration beginnen.
Abrechnungsclient initialisieren
Die ersten Schritte des Integrationsprozesses 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
enableBillingProgram(EnableBillingProgramParams)-Methode aufrufen, um anzugeben, dass Sie externe Zahlungen anbieten möchten. - Sie müssen ein
DeveloperProvidedBillingListenerregistrieren, um Fälle zu bearbeiten, in denen der Nutzer auf Ihrer Website oder in einer Zahlungs-App bezahlen möchte.
Im folgenden Beispiel wird ein BillingClient mit diesen Änderungen initialisiert:
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 die BillingClient initialisiert haben, stellen Sie eine Verbindung zu Google Play her, wie unter Mit Google Play verbinden beschrieben.
Nutzerberechtigung 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 infrage kommt. Diese Methode gibt BillingResponseCode.OK zurück, wenn der Nutzer berechtigt ist.
Das folgende Beispiel zeigt, wie die Berechtigung geprüft wird:
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.
}
});
Details dazu, wie Ihre App auf andere Antwortcodes reagieren sollte, finden Sie im Abschnitt Antworten verarbeiten. 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 verfügbare Produkte dem Nutzer 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 zum Kauf ausgewählt hat, starten Sie den externen Zahlungsablauf, wie im Abschnitt zum Starten des externen Zahlungsablaufs beschrieben.
Externes Transaktionstoken vorbereiten
Wenn Sie eine externe Transaktion an Google Play melden möchten, benötigen Sie ein externes Transaktionstoken, das über die Play Billing Library generiert wurde. Jedes Mal, wenn der Nutzer über die API für externe Zahlungen eine externe Website oder App aufruft, 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 Integration des Abrechnungssystems von Google Play, aber mit einem zusätzlichen Parameter DeveloperBillingOptionParams, der angibt, dass Ihre App den Ablauf für externe Zahlungen für diesen Kauf aktivieren möchte.
DeveloperBillingOptionParams muss Folgendes enthalten:
billingProgramauf das AbrechnungsprogrammEXTERNAL_PAYMENTSfestgelegtlinkURIauf das Linkziel festgelegtlaunchModeaufLAUNCH_IN_EXTERNAL_BROWSER_OR_APPfestlegen, wenn Google Play den Link starten soll, oder aufCALLER_WILL_LAUNCH_LINK, wenn Ihre App den Link starten soll.
Wenn Ihre App launchBillingFlow() mit dem bereitgestellten 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, das externe Zahlungen unterstützt (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 wurden, wird im Kaufvorgang die Benutzeroberfläche für die Auswahl des Nutzers angezeigt.
- Wenn externe Zahlungen nicht aktiviert sind, wird im Kaufvorgang die Standard-Benutzeroberfläche des Google Play-Abrechnungssystems ohne Auswahlmöglichkeit für Nutzer angezeigt.
- Wenn das Google Play-Land des Nutzers kein unterstütztes Land ist, wird im Kaufvorgang die Standard-Benutzeroberfläche 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 |
|
Externe Zahlungen aktiviert (BillingClient-Einrichtung und launchBillingFlow) |
Nutzer sieht die Benutzeroberfläche für die Einwilligung |
Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems |
Externe Zahlungen sind nicht aktiviert (entweder nicht bei der Einrichtung von BillingClient aktiviert oder DeveloperBillingOptionParams wurden nicht für launchBillingFlow bereitgestellt) |
Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems |
Nutzer sieht die Standard-UX des Google Play-Abrechnungssystems |
Das folgende Snippet zeigt, wie DeveloperBillingOptionParams erstellt wird:
Kotlin
val developerBillingOptionParams =
DeveloperBillingOptionParams.newBuilder()
.setBillingProgram(BillingProgram.EXTERNAL_PAYMENTS)
.setLinkUri("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("https://www.example.com/external/purchase")
.setLaunchMode(
DeveloperBillingOptionParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
.build();
Nutzerauswahl verarbeiten
Wie Sie den Rest des Kaufvorgangs abwickeln, hängt davon ab, ob der Nutzer das Abrechnungssystem von Google Play oder die Zahlung auf Ihrer Website ausgewählt hat.
Wenn der Nutzer auf Ihrer Website oder in einer Zahlungs-App bezahlen möchte
Wenn der Nutzer auf Ihrer Website bezahlen möchte, ruft Google Play die DeveloperProvidedBillingListener auf, um die App darüber zu informieren, dass der Nutzer auf Ihrer Website oder in einer Zahlungs-App bezahlen möchte. Insbesondere wird die Methode onUserSelectedDeveloperBilling() aufgerufen.
Wenn Ihre App launchMode auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP festlegt, wird der Link von Google Play gestartet. Wenn launchMode auf CALLER_WILL_LAUNCH_LINK gesetzt wurde, ist Ihre App für das Öffnen des Links verantwortlich.
Wenn Sie Nutzer mit einer Zahlungs-App verknüpfen, sind Sie dafür verantwortlich, zu 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 im Leitfaden zur Backend-Integration beschrieben.
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 externe Zahlungen 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 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 Abänderungen von Abos behandeln.
Abläufe für Upgrades und Downgrades
Änderungen von Abomodellen, einschließlich Upgrades und Downgrades, sollten unterschiedlich behandelt 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 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. Leiten Sie einen neuen Kaufvorgang mit launchBillingFlow() ein, wie unter Externen Zahlungsablauf 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 nach Wahl des Nutzers gekauft wurden, sollten Nutzer, die ein Upgrade oder Downgrade anfordern, die Website des Entwicklers oder eine Zahlungs-App verwenden, ohne die Auswahl des Nutzers noch einmal durchlaufen zu müssen.
Rufen Sie dazu launchBillingFlow() auf, wenn der Nutzer ein Upgrade oder Downgrade anfordert. Anstatt andere Parameter unter dem Objekt SubscriptionUpdateParams anzugeben, verwenden Sie setOriginalExternalTransactionId() und geben Sie die externe Transaktions-ID für den ursprünglichen Kauf an.
DeveloperBillingOptionParams muss in diesem Anruf ebenfalls angegeben werden. Der Bildschirm für die Nutzerauswahl wird nicht angezeigt, da die Nutzerauswahl für den ursprünglichen Kauf bei Upgrades und Downgrades beibehalten wird. Sie müssen für diese Transaktion ein neues externes Transaktionstoken generieren, wie hier beschrieben.
Wenn das Upgrade oder Downgrade über die Website des Entwicklers oder eine Zahlungs-App abgeschlossen wird, müssen Sie eine neue Transaktion melden. Verwenden Sie dazu das externe Transaktionstoken, das Sie beim vorherigen Aufruf für den Kauf des neuen Abos erhalten haben.
Abos, die über das Abrechnungssystem von Google Play gekauft wurden
Nutzer, die ihr aktuelles Abo nach der Einführung der Abrechnung mit Auswahlmöglichkeit für Nutzer über das Abrechnungssystem von Google Play gekauft haben, sollten ebenfalls den standardmäßigen Google Play Billing-Ablauf durchlaufen. DeveloperBillingOptionParams darf im Aufruf von launchBillingFlow nicht festgelegt werden.
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 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 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 API-Integration für externe Zahlungen behandeln.
Über die Website des Entwicklers 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 Verlängerungen einfach weiter melden, wenn der aktuelle Zyklus abläuft und die nächste Verlängerung erfolgt. Dazu gehören 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, das den Nutzer dazu anregen soll, sein Abo fortzusetzen.
Ü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 Echtzeit-Entwicklerbenachrichtigung vom Typ 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 Auswahlprozess 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 Nutzerwahlprozess aber nicht noch einmal durchlaufen. In diesem Fall wird für den Nutzer ein neues Kauf-Token ausgestellt.
Ihr Backend erhält eine Echtzeit-Entwicklerbenachrichtigung vom Typ SUBSCRIPTION_PURCHASED und der Wert von linkedPurchaseToken für den neuen Kaufstatus wird wie bei einem Upgrade oder Downgrade mit dem alten Kauf-Token für das gekündigte Abo festgelegt.
Abo fortsetzen
Wenn ein Abo vollständig abläuft, sei es aufgrund einer Kündigung oder eines Zahlungsablehnung ohne Wiederherstellung (eine abgelaufene Kontosperre), muss der Nutzer das Abo noch einmal abschließen, wenn er die Berechtigung wiederherstellen 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. 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() und launchBillingFlow() möglicherweise einen anderen BillingResponseCode als BillingResponseCode.OK zurück. So können Sie diese Antwortcodes verarbeiten:
BillingResponseCode.ERROR: Dies ist ein interner Fehler. Fahren Sie nicht mit der Transaktion fort und öffnen Sie die externe Website nicht. Wiederholen Sie den Vorgang, indem Sie die API noch einmal aufrufen.BillingResponseCode.FEATURE_NOT_SUPPORTED: Die APIs für externe Zahlungen werden vom Play Store auf dem aktuellen Gerät nicht unterstützt. Fahren Sie nicht mit der Transaktion fort und öffnen Sie die externe Website nicht.BillingResponseCode.DEVELOPER_ERROR: Bei der Anfrage ist ein Fehler aufgetreten. Verwenden Sie die Debugging-Meldung, um den Fehler zu identifizieren und zu beheben, bevor Sie fortfahren.BillingResponseCode.USER_CANCELED: Öffnen Sie die externe Website oder App nicht. Rufen SielaunchBillingFlow()noch einmal auf, um dem Nutzer das Informationsdialogfeld beim nächsten Versuch, ihn aus der App heraus zu leiten, zu präsentieren.BillingResponseCode.BILLING_UNAVAILABLE: Die Transaktion kommt nicht für externe Zahlungen infrage. Die Entwicklerabrechnung ist im Rahmen dieses Programms daher nicht verfügbar. Das kann daran liegen, dass der Nutzer sich nicht in einem für dieses Programm berechtigten Land befindet oder Ihr Konto nicht erfolgreich für das Programm registriert wurde. Wenn das der Fall ist, sehen Sie in der Play Console nach, ob Sie für das Programm registriert sind.BillingResponseCode.NETWORK_ERROR,BillingResponseCode.SERVICE_DISCONNECTED,BillingResponseCode.SERVICE_UNAVAILABLE: Dies sind vorübergehende Fehler, die mit einer geeigneten Richtlinie für Wiederholungsversuche behandelt werden sollten. Stellen Sie im Fall vonSERVICE_DISCONNECTEDeine Verbindung zu Google Play her, bevor Sie es noch einmal versuchen.
Links für externe Zahlungen testen
Mit Lizenztestern können Sie Ihre Integration für externe Zahlungen testen. Für Transaktionen, die von Lizenztesterkonten 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.