Anleitung zur In-App-Einbindung von Links zu externen Inhalten

In diesem Dokument wird beschrieben, wie Sie die APIs der Play Billing Library einbinden, um in berechtigten Apps Links zu externen Inhalten anzubieten. Dazu gehört auch die Möglichkeit, Nutzer in den USA aus Ihrer Play-App herauszuleiten, um ihnen Angebote für digitale In-App-Inhalte und App-Downloads zu präsentieren. 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 Links verwenden möchten, benötigen Sie Version 8.2 oder höher. Wenn Sie von einer früheren Version migrieren müssen, folgen Sie der Anleitung im Migrationsleitfaden, bevor Sie die Links zu externen Inhalten hinzufügen.

Abrechnungsclient initialisieren

Folgen Sie zum Initialisieren des Abrechnungsclients den Schritten unter BillingClient initialisieren mit den folgenden Änderungen:

  • Aktivieren Sie PurchasesUpdatedListener nicht. Dieser Listener ist für Links zu externen Inhalten nicht erforderlich.
  • Rufen Sie enableBillingProgram() mit BillingProgram.EXTERNAL_CONTENT_LINK auf, um anzugeben, dass Ihre App die Links zu externen Inhalten verwendet.

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

Kotlin

val billingClient = BillingClient.newBuilder(context)
  .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
  .build()

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .build();

Mit Google Play verbinden

Nachdem Sie 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, müssen Sie prüfen, ob der Nutzer für das Programm für externe Inhaltslinks infrage kommt. Rufen Sie dazu die Methode isBillingProgramAvailableAsync() auf. Diese Methode gibt BillingResponseCode.OK zurück, wenn der Nutzer die Voraussetzungen für das Programm für Links zu externen Inhalten erfüllt. Das folgende Beispiel zeigt, wie Sie prüfen, ob ein Nutzer berechtigt ist, Links zu externen Inhalten zu verwenden:

Kotlin

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return
        }

        // External content links are available. Prepare an external
        // transaction token.
      }
    })

Java

billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_CONTENT_LINK,
  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 content links unavailable, etc.
            return;
        }

        // External content links are available. Prepare 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.

Externes Transaktionstoken vorbereiten

Als Nächstes müssen Sie ein externes Transaktionstoken aus der Play-Abrechnungsbibliothek generieren. Jedes Mal, wenn der Nutzer über die API für externe Links eine externe Website aufruft, muss ein neues externes Transaktions-Token generiert werden. Dazu können Sie die createBillingProgramReportingDetailsAsync API aufrufen. Das Token sollte unmittelbar vor der Weiterleitung des Nutzers generiert werden.

Hinweis: Das Token für externe Transaktionen sollte niemals im Cache gespeichert werden. Generieren Sie jedes Mal, wenn der Nutzer weitergeleitet wird, ein neues Token.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink is called.
    }
  })

Java

BillingProgramReportingDetailsParams params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
        .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 when launchExternalLink is called.
      }
  });

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

Externen Link aufrufen

Sobald das externe Transaktions-Token bereit ist, kann der Nutzer über den Aufruf der Methode launchExternalLink aus der App heraus zu einem Angebot für digitale Inhalte oder einem App-Download weitergeleitet werden. Google Play rendert möglicherweise zusätzliche Informationsdialogfelder für den Nutzer, je nach seinen Einstellungen, wenn Sie diese API aufrufen.

Beim Aufrufen der Methode launchExternalLink müssen Details zum externen Link über LaunchExternalLinkParams angegeben werden. Diese Klasse enthält die folgenden Parameter:

  • Link-URI: Der Link zur externen Website, auf der die digitalen Inhalte oder der App-Download angeboten werden. Für App-Downloads muss dieser Link in der Play Console registriert und genehmigt werden.
  • Link Type (Linktyp): Der Typ des Inhalts, der dem Nutzer angeboten wird.
  • Launch-Modus: Gibt an, wie der Link geöffnet wird. Bei App-Downloads muss dieser Wert auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP festgelegt werden.

  • Abrechnungsprogramm: Setzen Sie dies auf BillingProgram.EXTERNAL_CONTENT_LINK.

Kotlin

val params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

val listener : LaunchExternalLinkResponseListener =
    object : LaunchExternalLinkResponseListener {
      override fun onLaunchExternalLinkResponse(
        billingResult: BillingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
}

billingClient.launchExternalLink(activity, params, listener)

Java

LaunchExternalLinkParams params =
  LaunchExternalLinkParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .setLinkUri(Uri.parse("https://www.myapprovedsite.com"))
    .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
    .setLaunchMode(
      LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP)
    .build()

LaunchExternalLinkResponseListener listener =
  new LaunchExternalLinkResponseListener() {
    @Override
    public void onLaunchExternalLinkResponse(BillingResult billingResult) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        // If Launch Mode was set to LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, the
        // user was directed outside of the app by Play. This does not give
        // any information on the user's actions during the link out, such
        // as if a transaction was completed.

        // If Launch Mode was set to CALLER_WILL_LAUNCH_LINK, then your app
        // may proceed to direct the user to the external website.
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Antwortverarbeitung

Wenn ein Fehler auftritt, geben die Methoden isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() und onLaunchExternalLinkResponse() möglicherweise einen BillingResponseCode zurück, der nicht BillingResponseCode.OK ist. So können Sie diese Antwortcodes verarbeiten:

  • 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 oder launchExternalLink() beim nächsten Versuch aufrufen, den Nutzer aus der App heraus zu leiten.
  • FEATURE_NOT_SUPPORTED: Die APIs für externe Inhaltslinks 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.
  • USER_CANCELED: Die externe Website wird nicht geöffnet. Rufen Sie launchExternalLink() noch einmal auf, wenn Sie das nächste Mal versuchen, den Nutzer aus der App herauszuleiten.
  • BILLING_UNAVAILABLE: Die Transaktion ist nicht für Links zu externen Inhalten geeignet und wird daher nicht im Rahmen dieses Programms ausgeführt. Das liegt entweder daran, dass der Nutzer nicht in einem für dieses Programm berechtigten Land ist oder dass 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.
  • 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.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Das sind vorübergehende Fehler, die mit einer geeigneten Wiederholungsrichtlinie behandelt werden sollten. Im Fall von SERVICE_DISCONNECTED stellen Sie eine Verbindung zu Google Play wieder her, bevor Sie es noch einmal versuchen.

Links zu externen Inhalten testen

Lizenztester sollten verwendet werden, um die Integration externer Angebote zu testen. Für Transaktionen, die von Konten von Lizenztestern 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 Back-End einbinden.