Руководство по интеграции в приложение для программы внешних предложений

В этом руководстве рассказывается, как интегрировать API для поддержки внешних предложений в приложениях, соответствующих требованиям, и в поддерживаемых регионах. Подробнее о программе внешних предложений…

Настройка библиотеки Play Платежей

Чтобы использовать API внешних предложений, добавьте в приложение для Android зависимость от библиотеки Play Платежей версии 8.2.1 или более новой. Если вам нужно перейти на более новую версию, следуйте инструкциям в руководстве по переносу, прежде чем пытаться реализовать внешние предложения.

Как подключить Google Play

Первые шаги интеграции такие же, как описанные в руководстве по интеграции платежной системы, но вам нужно вызвать enableBillingProgram, чтобы указать, что вы хотите использовать внешние предложения при инициализации BillingClient:

В примере ниже показано, как инициализировать BillingClient с этими изменениями:

Kotlin

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

Java

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

После инициализации BillingClient вам нужно установить подключение к Google Play, как описано в руководстве по интеграции.

Проверить доступность

Чтобы проверить, доступны ли внешние предложения текущему пользователю, вызовите метод isBillingProgramAvailableAsync.

Этот API возвращает BillingResponseCode.OK, если внешние предложения доступны. Подробнее о том, как ваше приложение должно реагировать на другие коды ответа, рассказывается в разделе обработки ответов.

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

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

Как подготовить токен внешней транзакции

Чтобы сообщить о внешней транзакции в Google Play, вам понадобится токен внешней транзакции, сгенерированный библиотекой Play Платежей. Этот токен можно получить, вызвав API createBillingProgramReportingDetailsAsync. Для каждого внешнего предложения необходимо генерировать новый токен непосредственно перед тем, как перенаправлять пользователя за пределы приложения. Токены не должны кешироваться между транзакциями.

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

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

Вы также можете запросить функцию suspend createBillingProgramReportingDetailsAsync с помощью расширений Kotlin, чтобы не определять прослушиватель:

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

Запуск процесса внешнего предложения

Чтобы запустить процесс внешнего предложения, ваше приложение должно вызвать API launchExternalLink() из основного потока. Этот API принимает на вход объект LaunchExternalLinkParams. Чтобы создать объект LaunchExternalLinkParams, используйте класс LaunchExternalLinkParams.Builder. Этот класс содержит следующие параметры:

• linkUri – ссылка на внешний сайт, где предлагается цифровой контент или скачивание приложения. Если вы хотите показывать ссылки на скачивание приложений, их нужно зарегистрировать и одобрить в Play Console.
• linkType – тип контента, предлагаемого пользователю.
• launchMode – определяет, как запускается ссылка. Если вы хотите увеличить число скачиваний приложения, укажите значение LAUNCH_IN_EXTERNAL_BROWSER_OR_APP.
• billingProgram – установите значение BillingProgram.EXTERNAL_OFFER.

Когда вы вызываете функцию launchExternalLink(), пользователю могут показываться диалоговые окна с дополнительной информацией в зависимости от его настроек. В зависимости от параметра launchMode Google Play либо открывает URI ссылки во внешнем браузере, либо возвращает поток в ваше приложение, чтобы запустить URI. В большинстве случаев можно использовать режим LAUNCH_IN_EXTERNAL_BROWSER_OR_APP, в котором Google Play запускает URI. Если вам нужно более сложное поведение, например запуск URI в представлении WebView или открытие URI в определенном браузере, вы можете использовать режим CALLER_WILL_LAUNCH_LINK. Чтобы защитить конфиденциальность пользователей, убедитесь, что URI не содержит информацию, позволяющую идентифицировать личность.

Примечание. Пользователи могут не вернуться в ваше приложение после того, как URI ссылки будет открыт во внешнем браузере или приложении. Выполните все необходимые задачи в приложении, прежде чем вызывать launchExternalLink().

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)
Integration.kt

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

Если вы задали для LaunchMode значение CALLER_WILL_LAUNCH_LINK, перенаправляйте пользователя за пределы приложения, только если onLaunchExternalLinkResponse предоставляет BillingResponseCode.OK.

Как сообщать о транзакциях в Google Play

Примечание. Требования к отчетности о транзакциях приведены в разделе Как зарегистрироваться в программе внешних предложений.

Вы должны сообщать обо всех внешних транзакциях в Google Play, вызывая Google Play Developer API из своего внутреннего сервиса. При отправке отчета о транзакции необходимо указать externalTransactionToken, полученный от API createBillingProgramReportingDetailsAsync. Если пользователь совершает несколько покупок, вы можете использовать один и тот же параметр externalTransactionToken для каждой из них. Информацию о том, как сообщать о транзакциях, можно найти в руководстве по интеграции бэкенда.

Обработка ответов

При возникновении ошибки методы isBillingProgramAvailableAsync(), createBillingProgramReportingDetailsAsync() и launchExternalLink() могут возвращать ответы, отличные от BillingResponseCode.OK. Рекомендуем обрабатывать эти коды ответов следующим образом:

• ERROR: внутренняя ошибка. Не совершайте транзакцию и не переходите на внешний сайт. Повторите попытку, вызвав функцию launchExternalLink(), чтобы показать пользователю диалоговое окно с информацией при следующей попытке перенаправить его за пределы приложения.
• FEATURE_NOT_SUPPORTED: API внешних предложений не поддерживаются Google Play на текущем устройстве. Не совершайте транзакцию и не переходите на внешний сайт.
• USER_CANCELED: не открывайте внешний сайт. Вызовите функцию Call launchExternalLink() ещё раз, чтобы показать пользователю диалоговое окно с информацией при следующей попытке перенаправить его за пределы приложения.
• BILLING_UNAVAILABLE: транзакция не соответствует требованиям для внешних предложений, поэтому ее нельзя проводить в рамках этой программы. Это может быть связано с тем, что пользователь находится в стране, где программа недоступна, или ваш аккаунт не зарегистрирован в программе. Если это так, проверьте статус регистрации в Play Console.
• DEVELOPER_ERROR: в запросе есть ошибка. Используйте сообщение об ошибке, чтобы определить и устранить ее.
• NETWORK_ERROR, SERVICE_DISCONNECTED, SERVICE_UNAVAILABLE – временные ошибки, которые следует обрабатывать с помощью подходящих правил повторных попыток. Если вы используете устройство SERVICE_DISCONNECTED, перед повторной попыткой восстановите подключение к Google Play.

Как тестировать внешние предложения

Тестировщики лицензий нужны для проверки интеграции внешних предложений. Счета за транзакции, инициированные аккаунтами тестировщиков лицензий, выставляться не будут. Подробнее о том, как настроить тестировщиков лицензий…

Дальнейшие действия

После того как вы завершите интеграцию в приложении, можно будет интегрировать серверную часть.