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 Eignungsvoraussetzungen und des geografischen Geltungsbereichs, finden Sie hier.

Einrichtung der Play Billing Library

Wenn Sie die APIs für externe Angebote verwenden möchten, müssen Sie die Abhängigkeit der Play Billing Library ab Version 8.2 in Ihre Android-App einfügen. Wenn Sie von einer früheren Version migrieren müssen, folgen Sie der Anleitung im Migrationshandbuch, bevor Sie versuchen, externe Angebote zu implementieren.

Mit Google Play verbinden

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

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

Kotlin

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

Java

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

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

Verfügbarkeit prüfen

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

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

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 über die 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 der Weiterleitung des Nutzers an einen Ort außerhalb 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 Funktion „suspend“ createBillingProgramReportingDetailsAsync mit Kotlin-Erweiterungen abfragen, sodass Sie keinen Listener definieren müssen:

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

Ablauf für externes Angebot starten

Um einen Ablauf für ein externes Angebot zu starten, muss Ihre berechtigte App die launchExternalLink() API über den Hauptthread Ihrer App aufrufen. Diese API akzeptiert ein LaunchExternalLinkParams-Objekt als Eingabe. Verwenden Sie die Klasse LaunchExternalLinkParams.Builder, 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 geöffnet wird. Bei App-Downloads muss dieser Wert auf LAUNCH_IN_EXTERNAL_BROWSER_OR_APP festgelegt werden.
  • billingProgram: Setzen Sie diesen Wert auf BillingProgram.EXTERNAL_OFFER.

Wenn Sie launchExternalLink() aufrufen, werden dem Nutzer je nach seinen Einstellungen möglicherweise zusätzliche Informationsdialogfelder angezeigt. Je nach Parameter launchMode wird der Link-URI entweder in einem externen Browser gestartet oder der Ablauf wird an Ihre App zurückgegeben, damit der URI gestartet wird. In den meisten Fällen können Sie den Modus LAUNCH_IN_EXTERNAL_BROWSER_OR_APP verwenden, in dem der URI von Google Play gestartet wird. Wenn Sie ein benutzerdefiniertes Verhalten wünschen, z. B. das Starten des URI in einer Webview oder das Öffnen des URI in einem bestimmten Browser, können Sie den Modus CALLER_WILL_LAUNCH_LINK verwenden. Aus Datenschutzgründen darf keine personenidentifizierbare Information in der URI übergeben werden.

Kotlin


// An activity reference from which the external offers flow will be launched.
val 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 {
      override fun 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)

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 setzen, sollten Sie den Nutzer nur dann aus der App herausleiten, wenn onLaunchExternalLinkResponse BillingResponseCode.OK bereitstellt.

Transaktionen bei 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 eine externalTransactionToken angeben, die Sie über die createBillingProgramReportingDetailsAsync API erhalten haben. Wenn ein Nutzer mehrere Käufe tätigt, können Sie für jeden Kauf denselben externalTransactionToken verwenden. 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 können Sie diese Antwortcodes behandeln:

  • ERROR: Dies ist ein interner Fehler. Fahren Sie nicht mit der Transaktion fort und öffnen Sie die externe Website nicht. Versuchen Sie es noch einmal, indem Sie launchExternalLink() aufrufen, um dem Nutzer beim nächsten Versuch, ihn aus der App herauszuleiten, das Informationsdialogfeld anzuzeigen.
  • 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 die externe Website nicht.
  • USER_CANCELED: Die externe Website wird nicht geöffnet. Rufen Sie launchExternalLink() noch einmal auf, um dem Nutzer das Informationsdialogfeld beim nächsten Versuch, ihn aus der App herauszuleiten, anzuzeigen.
  • BILLING_UNAVAILABLE: Die Transaktion ist nicht für externe Angebote berechtigt und sollte daher nicht im Rahmen dieses Programms abgewickelt werden. Das kann daran liegen, dass der Nutzer nicht in einem für dieses Programm berechtigten Land ist oder Ihr Konto nicht erfolgreich für das Programm registriert wurde. Wenn das der Fall ist, prüfen Sie Ihren Registrierungsstatus in der Play Console.
  • 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.

Externe Angebote 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 Backend einbinden.