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

In diesem Leitfaden wird beschrieben, wie Sie die APIs einbinden, um externe Angebote in berechtigten Apps 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 Sie die APIs für externe Angebote verwenden möchten, fügen Sie Ihrer Android-App die Abhängigkeit der Play Billing Library in Version 8.2.1 oder höher hinzu. Wenn Sie von einer früheren Version migrieren müssen, folgen Sie der Anleitung im Migrationsleitfaden, bevor Sie versuchen, externe Angebote zu implementieren.

Mit Google Play verbinden

Die ersten Schritte im Integrationsprozess sind dieselben wie in dem Leitfaden zur Abrechnungsintegration beschrieben. Sie müssen jedoch enableBillingProgram aufrufen, um anzugeben, dass Sie externe Angebote verwenden möchten, wenn Sie Ihren BillingClient initialisieren:

Im folgenden Beispiel wird die Initialisierung eines BillingClient mit diesen Änderungen veranschaulicht:

Kotlin

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

Java

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

Nachdem Sie den BillingClient initialisiert haben, müssen Sie eine Verbindung zu Google Play herstellen, wie im Integrationsleitfaden beschrieben.

Verfügbarkeit prüfen

Um zu bestätigen, dass externe Angebote für den aktuellen Nutzer verfügbar sind, rufen Sie isBillingProgramAvailableAsync auf.

Diese API gibt BillingResponseCode.OK zurück, wenn externe Angebote verfügbar sind. Unter Antwortverarbeitung finden Sie weitere Informationen dazu, wie Ihre App auf andere Antwortcodes reagieren sollte.

Kotlin

billingClient.isBillingProgramAvailableAsync(
    BillingProgram.EXTERNAL_OFFER,
    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 offers unavailable, etc.
                return
            }

            // External offers are available. Continue with steps in the
            // guide.
        }
    }
)

Java


billingClient.isBillingProgramAvailableAsync(
  BillingProgram.EXTERNAL_OFFER,
  new BillingProgramAvailabilityListener() {
    @Override
    public void onBillingProgramAvailabilityResponse(
      BillingResult billingResult,
      BillingProgramAvailabilityDetails billingProgramAvailabilityDetails) {
        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

Wenn Sie eine externe Transaktion an Google Play melden möchten, benötigen Sie ein externes Transaktionstoken, das von der Play Billing Library generiert wurde. Sie können dieses Token abrufen, indem Sie die createBillingProgramReportingDetailsAsync API aufrufen. Für jedes externe Angebot muss unmittelbar vor dem Weiterleiten des Nutzers aus der App ein neues Token generiert werden. Tokens dürfen nicht transaktionsübergreifend im Cache gespeichert werden.

Kotlin

val params =
    BillingProgramReportingDetailsParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        .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 transaction token in your backend. You may pass it
            // to the external website when calling the launchExternalLink API.
        }
    }
)

Java

BillingProgramReportingDetailsParams params =
  BillingProgramReportingDetailsParams.newBuilder()
    .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
    .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 transaction token in your backend. You may pass it
        // to the external website when calling the launchExternalLink API.
      }
});

Alternativ können Sie die suspend-Funktion createBillingProgramReportingDetailsAsync mit Kotlin-Erweiterungen abfragen, so dass Sie keinen Listener definieren müssen:

val createBillingProgramReportingDetailsResult =
    withContext(coroutineContext) {
        billingClient
            .createBillingProgramReportingDetails(params)
    }
// Process the result

Ablauf für externe Angebote starten

Wenn Sie einen Ablauf für externe Angebote starten möchten, muss Ihre berechtigte App die launchExternalLink() API über den Hauptthread Ihrer App aufrufen. Diese API akzeptiert ein LaunchExternalLinkParams-Objekt als Eingabe. Verwenden Sie die LaunchExternalLinkParams.Builder Klasse, um ein LaunchExternalLinkParams Objekt zu erstellen. Diese Klasse enthält die folgenden Parameter:

  • linkUri : 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.
  • linkType : Der Typ der Inhalte, die dem Nutzer angeboten werden.
  • launchMode : Gibt an, wie der Link gestartet wird. Für App-Downloads müssen Sie diesen Parameter auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP festlegen.
  • billingProgram : Legen Sie diesen Parameter auf BillingProgram.EXTERNAL_OFFER fest.

Wenn Sie launchExternalLink() aufrufen, werden dem Nutzer je nach seinen Nutzereinstellungen möglicherweise zusätzliche Informationen dialogfelder angezeigt. Je nach Parameter launchMode startet Play entweder den Link-URI in einem externen Browser oder leitet den Ablauf an Ihre App zurück, damit diese den URI starten kann. In den meisten Fällen können Sie den LAUNCH_IN_EXTERNAL_BROWSER_OR_APP Modus verwenden, in dem Play den URI für Sie startet. Wenn Sie ein individuelleres Verhalten wünschen, z. B. den URI in einer WebView starten oder den URI in einem bestimmten Browser öffnen, können Sie den CALLER_WILL_LAUNCH_LINK Modus verwenden. Achten Sie aus Datenschutzgründen darauf, dass im URI keine personenidentifizierbaren Informationen weitergegeben werden.

Kotlin

// An activity reference from which the external offers flow will be launched.
val activity = this.activity

val params =
    LaunchExternalLinkParams.newBuilder()
        .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
        // You can pass along the external transaction token from
        // BillingProgramReportingDetails as a URL parameter in the URI
        .setLinkUri(yourLinkUri)
        .setLinkType(LaunchExternalLinkParams.LinkType.LINK_TO_APP_DOWNLOAD)
        .setLaunchMode(
            LaunchExternalLinkParams.LaunchMode.LAUNCH_IN_EXTERNAL_BROWSER_OR_APP
        )
        .build()

val listener: LaunchExternalLinkResponseListener =
    LaunchExternalLinkResponseListener { billingResult ->
        if (billingResult.responseCode == BillingResponseCode.OK) {
            // Proceed with the rest of the external offer flow. If the user
            // purchases an item, be sure to report the transaction to Google Play.
        } else {
            // Handle failures such as retrying due to network errors.
        }
    }

billingClient.launchExternalLink(activity, params, listener)

Java


// An activity reference from which the external offers flow will be launched.
Activity activity = ...;

LaunchExternalLinkParams params = LaunchExternalLinkParams.newBuilder()
  .setBillingProgram(BillingProgram.EXTERNAL_OFFER)
  // You can pass along the external transaction token from  
  // BillingProgramReportingDetails as a URL parameter in the URI
  .setLinkUri(yourLinkUri)
  .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.responseCode == BillingResponseCode.OK) {
        // Proceed with the rest of the external offer flow. If the user
        // purchases an item, be sure to report the transaction to Google
        // Play.
      } else {
        // Handle failures such as retrying due to network errors.
      }
    }
  }

billingClient.launchExternalLink(activity, params, listener);

Wenn Sie LaunchMode auf CALLER_WILL_LAUNCH_LINK festlegen, sollten Sie den Nutzer nur dann aus der App weiterleiten, wenn onLaunchExternalLinkResponse den Wert BillingResponseCode.OK zurückgibt.

Transaktionen an Google Play melden

Sie müssen alle externen Transaktionen an Google Play melden, indem Sie die Google Play Developer API über Ihr Backend aufrufen. Wenn Sie eine Transaktion melden, müssen Sie ein externalTransactionToken angeben, das Sie über die createBillingProgramReportingDetailsAsync API erhalten haben. Wenn ein Nutzer mehrere Käufe tätigt, können Sie dasselbe externalTransactionToken verwenden, um jeden Kauf zu melden. Informationen zum Melden einer Transaktion finden Sie im Leitfaden zur Backend-Integration.

Antwortverarbeitung

Wenn ein Fehler auftritt, geben die Methoden isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() und launchExternalLink() möglicherweise andere Antworten 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 launchExternalLink() aufrufen, um dem Nutzer das Informationsdialogfeld anzuzeigen, wenn Sie ihn das nächste Mal aus 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: Öffnen Sie die externe Website nicht. Rufen Sie launchExternalLink() noch einmal auf, um dem Nutzer das Informationsdialogfeld anzuzeigen, wenn Sie ihn das nächste Mal aus der App weiterleiten.
  • BILLING_UNAVAILABLE: Die Transaktion ist nicht für externe Angebote berechtigt und sollte daher nicht im Rahmen dieses Programms fortgesetzt werden. Das liegt entweder daran, dass der Nutzer sich nicht in einem für dieses Programm berechtigten Land befindet oder dass Ihr Konto nicht erfolgreich für das Programm registriert wurde. Wenn Letzteres der Fall ist, prüfen Sie den Registrierungsstatus in der Play Console.
  • DEVELOPER_ERROR: Es liegt ein Fehler in der Anfrage vor. Verwenden Sie die Debug-Nachricht, 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. Im Fall von SERVICE_DISCONNECTED müssen Sie eine Verbindung zu Google Play wiederherstellen, bevor Sie es noch einmal versuchen.

Externe Angebote testen

Lizenztester sollten verwendet werden, um die Integration externer 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-Integration abgeschlossen haben, können Sie Ihr Backend einbinden.