Anleitung zur In-App-Integration für das Programm für externe Angebote

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:

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

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.

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

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.

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

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.

// 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)

// 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 dazu showExternalOfferInformationDialog() 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 Sie showExternalOfferInformationDialog() 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 von SERVICE_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.