In diesem Leitfaden wird beschrieben, wie du die APIs einbindest, um externe Angebote in berechtigten Anwendungen und Regionen zu unterstützen. Weitere Informationen zum Programm für externe Angebote, einschließlich der Teilnahmevoraussetzungen und des geografischen Geltungsbereichs, finden Sie unter Programmanforderungen.
Play Billing Library einrichten
Wenn du die APIs für externe Angebote verwenden möchtest, musst du deiner Android-App Version 6.2.1 oder höher der Play Billing Library-Abhängigkeit hinzufügen. Wenn du von einer früheren Version migrieren musst, folge der Anleitung im Migrationsleitfaden, bevor du externe Angebote implementierst.
Mit Google Play verbinden
Die ersten Schritte im Integrationsprozess sind dieselben wie im Leitfaden zur Abrechnungseinbindung beschrieben. Es gibt aber einige Änderungen bei der Initialisierung von BillingClient
:
- Du musst eine neue Methode aufrufen, um anzugeben, dass du externe Angebote verwenden möchtest:
enableExternalOffer
.
Das folgende Beispiel zeigt, wie ein BillingClient
mit diesen Änderungen initialisiert wird:
Kotlin
var billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build()
Java
private BillingClient billingClient = BillingClient.newBuilder(context)
.enableExternalOffer()
.build();
Nach dem Initialisieren von BillingClient
müssen Sie eine Verbindung zu Google Play herstellen, wie im Integrationsleitfaden beschrieben.
Verfügbarkeit prüfen
Deine App sollte durch Aufrufen von isExternalOfferAvailableAsync
bestätigen, dass externe Angebote verfügbar sind.
Diese API gibt BillingResponseCode.OK
zurück, wenn externe Angebote verfügbar sind.
Weitere Informationen dazu, wie Ihre Anwendung auf andere Antwortcodes reagieren sollte, finden Sie unter Antwortbehandlung.
Kotlin
billingClient.isExternalOfferAvailableAsync(
object : ExternalOfferAvailabilityListener {
override fun onExternalOfferAvailabilityResponse(
billingResult: BillingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers unavailable, etc.
return
}
// External offers are available. Continue with steps in the
// guide.
})
Java
billingClient.isExternalOfferAvailableAsync(
new ExternalOfferAvailabilityListener() {
@Override
public void onExternalOfferAvailabilityResponse(
BillingResult billingResult) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors,
// handling external offers being unavailable, etc.
return;
}
// External offers are available. Continue with steps in the
// guide.
}
});
Externes Transaktionstoken vorbereiten
Zum Melden einer externen Transaktion an Google Play benötigst du ein externes Transaktionstoken, das aus der Play Billing Library generiert wurde. Jedes Mal, wenn der Nutzer eine externe Website über die externe Offers API besucht, muss ein neues externes Transaktionstoken generiert werden. Dazu rufen Sie die createExternalOfferReportingDetailsAsync
API auf. Dieses Token sollte generiert werden, unmittelbar bevor der Nutzer aus der App weitergeleitet wird. Es sollte niemals im Cache gespeichert werden und jedes Mal, wenn der Nutzer zu einer Seite außerhalb der App weitergeleitet wird, ein neues Token generiert werden.
Kotlin
billingClient.createExternalOfferReportingDetailsAsync(
object : ExternalOfferReportingDetailsListener {
override fun onExternalOfferReportingDetailsResponse(
billingResult: BillingResult,
externalOfferReportingDetails: ExternalOfferReportingDetails?) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return
}
val externalTransactionToken =
externalOfferReportingDetails?.externalTransactionToken
// Persist the transaction token locally. Pass it to the external
// website when showExternalOfferInformationDialog is called.
}
})
Java
billingClient.createExternalOfferReportingDetailsAsync(
new ExternalOfferReportingDetailsListener() {
@Override
public void onExternalOfferReportingDetailsResponse(
BillingResult billingResult,
@Nullable ExternalOfferReportingDetails
externalOfferReportingDetails) {
if (billingResult.getResponseCode() != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
return;
}
String transactionToken =
externalOfferReportingDetails.getExternalTransactionToken();
// Persist the external transaction token locally. Pass it to the
// external website when showExternalOfferInformationDialog is
// called.
}
});
Informationsdialogfeld für Nutzer
Zur Einbindung in externe Angebote muss deine berechtigte App einen Bildschirm mit Informationen anzeigen, auf dem Nutzer darüber informiert werden, dass sie gleich von der App zu einer externen Website weitergeleitet werden. Der Informationsbildschirm muss Nutzern durch Aufrufen der showExternalOfferInformationDialog
API angezeigt werden, bevor jedes Mal eine Verknüpfung mit einem externen Angebot erstellt wird.
Kotlin
// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;
val listener : ExternalOfferInformationDialogListener =
ExternalOfferInformationDialogListener {
override fun onExternalOfferInformationDialogResponse(
billingResult: BillingResult){
// Check billingResult
}
}
val billingResult = billingClient.showExternalOfferInformationDialog(
activity, listener)
Java
// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;
ExternalOfferInformationDialogListener listener =
new ExternalOfferInformationDialogListener() {
@Override
public void onExternalOfferInformationDialogResponse(
BillingResult billingResult) {
if (billingResult.responseCode != BillingResponseCode.OK) {
// Handle failures such as retrying due to network errors.
}
// Open the external website, passing along the external transaction
// token as a URL parameter. If the user purchases an item, be sure
// to report the transaction to Google Play.
}
}
BillingResult billingResult =
billingClient.showExternalOfferInformationDialog(activity, listener);
Wenn diese Methode BillingResponseCode.OK
zurückgibt, kann Ihre App den Nutzer zur externen Website weiterleiten. Wenn die Methode BillingResponseCode.USER_CANCELED
zurückgibt, darf Ihre App nicht mit dem Öffnen der Website fortfahren.
Transaktionen an Google Play melden
Alle externen Transaktionen müssen an Google Play gemeldet werden. Rufen Sie dazu die Google Play Developer API über Ihr Back-End auf. Externe Transaktionen müssen gemeldet werden, während ein externalTransactionToken
bereitgestellt wird, das mit der createExternalOfferReportingDetailsAsync
API abgerufen wurde. Wenn ein Nutzer mehrere Käufe tätigt, kannst du jeden einzelnen Kauf über dieselbe externalTransactionToken
melden. Informationen zum Melden einer Transaktion finden Sie im Leitfaden zur Back-End-Integration.
Umgang mit Antworten
Wenn ein Fehler auftritt, geben die Methoden isExternalOfferAvailableAsync
, createExternalOfferReportingDetailsAsync
und showExternalOfferInformationDialog
möglicherweise andere Antworten als BillingResponseCode.OK
zurück. Sie sollten diese Antwortcodes folgendermaßen verarbeiten:
ERROR
: Das ist ein interner Fehler. Fahren Sie nicht mit der Transaktion fort und öffnen Sie nicht die externe Website. Versuchen Sie es noch einmal. Rufen Sie dazushowExternalOfferInformationDialog()
auf. Dadurch wird dem Nutzer das Informationsdialogfeld angezeigt, wenn Sie den Nutzer das nächste Mal zu einer Seite außerhalb der App weiterleiten.FEATURE_NOT_SUPPORTED
: Die APIs für externe Angebote werden vom Play Store auf dem aktuellen Gerät nicht unterstützt. Fahren Sie nicht mit der Transaktion fort und öffnen Sie nicht die externe Website.USER_CANCELED
: Die externe Website wird nicht geöffnet. Rufen SieshowExternalOfferInformationDialog()
noch einmal auf, damit das Dialogfeld mit Informationen dem Nutzer angezeigt wird, wenn Sie ihn das nächste Mal zu einer Seite außerhalb der App weiterleiten.BILLING_UNAVAILABLE
: Die Transaktion kommt nicht für externe Angebote infrage und sollte daher im Rahmen dieses Programms nicht fortgesetzt werden. Das liegt entweder daran, dass sich der Nutzer in einem Land befindet, das nicht für dieses Programm geeignet ist, oder dass sich dein Konto nicht erfolgreich für das Programm angemeldet hat. Sollte dies Letzteres sein, überprüfen Sie Ihren 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 mit einer geeigneten Wiederholungsrichtlinie behoben werden sollten. Stellen Sie im Fall vonSERVICE_DISCONNECTED
wieder eine Verbindung zu Google Play her, bevor Sie es noch einmal versuchen.
Externe Angebote testen
Lizenztester sollten zum Testen der Einbindung deiner externen Angebote 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.