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

В этом документе описывается, как интегрировать API библиотеки Play Billing для предоставления ссылок на внешний контент в соответствующих приложениях. Это включает в себя возможность перенаправлять пользователей в США за пределы вашего приложения Play, чтобы предоставлять им предложения по внутриигровому цифровому контенту и загрузке приложений. Для получения дополнительной информации об этой программе см. требования программы .

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

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

Инициализируйте клиент выставления счетов.

Для инициализации биллингового клиента выполните те же действия, что описаны в разделе «Инициализация BillingClient , со следующими изменениями:

  • Не включайте обработчик PurchasesUpdatedListener — он не нужен для ссылок на внешний контент.
  • Вызовите enableBillingProgram() с BillingProgram.EXTERNAL_CONTENT_LINK чтобы указать, что ваше приложение использует внешние ссылки на контент.

В следующем примере показана инициализация объекта BillingClient с учетом внесенных изменений:

Котлин 

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

Java 

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

Подключиться к Google Play

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

Проверить соответствие пользователя требованиям

После подключения к Google Play необходимо проверить, имеет ли пользователь право на участие в программе внешних ссылок на контент, вызвав метод isBillingProgramAvailableAsync() . Этот метод возвращает BillingResponseCode.OK , если пользователь имеет право на участие в программе внешних ссылок на контент. В следующем примере показано, как проверить право пользователя на участие во внешней программе ссылок на контент:

Котлин 

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

    });

Подробности о том, как ваше приложение должно реагировать на другие коды ответов, см. в разделе обработки ответов . Если вы используете расширения Kotlin , вы можете использовать сопрограммы Kotlin, поэтому вам не нужно определять отдельный обработчик событий.

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

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

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

Котлин 

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

Если вы используете расширения Kotlin , вы можете использовать сопрограммы Kotlin, поэтому вам не нужно определять отдельный обработчик событий.

Перейти по внешней ссылке

После того, как внешний токен транзакции будет готов, пользователь может перейти по ссылке за пределами приложения к предложению цифрового контента или загрузке приложения, вызвав метод launchExternalLink . В зависимости от настроек пользователя при вызове этого API Google Play может отображать пользователю дополнительные информационные диалоги.

При вызове метода launchExternalLink необходимо указать сведения о внешней ссылке через LaunchExternalLinkParams . Этот класс содержит следующие параметры:

  • URI ссылки — это ссылка на внешний веб-сайт, где предлагается загрузить цифровой контент или приложение. Для загрузки приложений эта ссылка должна быть зарегистрирована и одобрена в консоли разработчика Play.
  • Тип ссылки — тип контента, предлагаемого пользователю.
  • Режим запуска — определяет способ запуска ссылки. Для загрузки приложений необходимо установить значение LAUNCH_IN_EXTERNAL_BROWSER_OR_APP .

  • Программа выставления счетов — установите значение BillingProgram.EXTERNAL_CONTENT_LINK .

Котлин 

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

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

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

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

Проверка внешних ссылок на контент

Для проверки интеграции внешних предложений следует использовать тестовые учетные записи лицензий. Счета за транзакции, инициированные учетными записями тестовых учетных записей лицензий, выставляться не будут. Дополнительную информацию о настройке тестовых учетных записей лицензий см. в разделе «Тестирование внутриприложенийных платежей с использованием лицензирования приложений» .

Следующие шаги

После завершения интеграции внутри приложения вы готовы интегрировать свой бэкэнд .