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

In diesem Dokument wird beschrieben, wie Sie die Play Billing Library APIs in unterstützte Apps einbinden, um Links zu externen Inhalten anzubieten. Dazu gehört die Möglichkeit, Nutzer in den USA außerhalb Ihrer Google Play-App zu Angeboten für digitale In-App-Inhalte und App-Downloads weiterzuleiten. 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 Links verwenden möchten, benötigen Sie Version 8.2.1 oder höher. Wenn Sie von einer älteren 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 derselben Anleitung wie unter initialisieren. Nehmen Sie dabei die folgenden Änderungen vor:BillingClient

  • Aktivieren Sie nicht PurchasesUpdatedListener. 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 Links zu externen Inhalten verwendet.

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

Kotlin

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

Java

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableBillingProgram(BillingProgram.EXTERNAL_CONTENT_LINK)
    .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.

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 Links zu externen Inhalten berechtigt ist. Rufen Sie dazu die isBillingProgramAvailableAsync() Methode auf. Diese Methode gibt BillingResponseCode.OK zurück, wenn der Nutzer für das Programm für Links zu externen Inhalten berechtigt ist. Im folgenden Beispiel wird gezeigt, wie Sie die Nutzerberechtigung für Links zu externen Inhalten prüfen:

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_CONTENT_LINK,
    object : BillingProgramAvailabilityListener {
        override fun onBillingProgramAvailabilityResponse(
            billingResult: BillingResult,
            billingProgramAvailabilityDetails: BillingProgramAvailabilityDetails
        ) {
            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.
      }

    });

Im Abschnitt 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.

Token für externe Transaktionen vorbereiten

Als Nächstes müssen Sie ein Token für externe Transaktionen aus der Play Billing Library generieren. Jedes Mal, wenn der Nutzer über die API für externe Links eine externe Website aufruft, muss ein neues Token für externe Transaktionen 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. Sie müssen jedes Mal ein neues Token generieren, wenn der Nutzer weitergeleitet wird.

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 starten

Sobald das Token für externe Transaktionen bereit ist, kann der Nutzer über die Methode launchExternalLink von der App zu einem Angebot für digitale Inhalte oder einem App-Download weitergeleitet werden. Je nach den Nutzereinstellungen werden in Google Play möglicherweise zusätzliche Informationsdialogfelder für den Nutzer gerendert, wenn Sie diese API aufrufen.

Beim Aufruf der launchExternalLink Methode 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 sein.
  • Linktyp : Der Typ der Inhalte, die dem Nutzer angeboten werden.
  • Startmodus : Gibt an, wie der Link gestartet wird. Für App-Downloads müssen Sie diesen auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP festlegen.

  • Abrechnungsprogramm : Legen Sie diesen auf BillingProgram.EXTERNAL_CONTENT_LINK fest.

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(), und createBillingProgramReportingDetailsAsync(), und onLaunchExternalLinkResponse() möglicherweise einen anderen BillingResponseCode als BillingResponseCode.OK zurück. So sollten Sie mit diesen Antwortcodes umgehen:

  • 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 oder launchExternalLink() aufrufen, wenn Sie den Nutzer das nächste Mal von der App weiterleiten möchten.
  • FEATURE_NOT_SUPPORTED: Die APIs für Links zu externen Inhalten 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: Öffnen Sie die externe Website nicht. Rufen Sie launchExternalLink() noch einmal auf, wenn Sie den Nutzer das nächste Mal von der App weiterleiten möchten.
  • BILLING_UNAVAILABLE: Die Transaktion ist nicht für Links zu externen Inhalten geeignet. Fahren Sie daher nicht mit diesem Programm fort. Das liegt entweder daran, 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. Im letzteren Fall prüfen Sie den Registrierungsstatus in der Play Console.
  • 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.
  • NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE: Dies sind vorübergehende Fehler, die mit einer geeigneten Wiederholungsrichtlinie behandelt werden sollten. Bei SERVICE_DISCONNECTED stellen Sie vor dem Wiederholen eine Verbindung zu Google Play her.

Links zu externen Inhalten testen

Lizenztester sollten verwendet werden, um die Einbindung Ihrer externen Angebote 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 Back-End einbinden.