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

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

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

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

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

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

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

В следующем примере показана инициализация BillingClient с этими изменениями:

Котлин 

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

Ява 

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

Ява 

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

Ява 

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 . Google Play может отображать пользователю дополнительные информационные диалоги в зависимости от его настроек при вызове этого API.

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

  • URL ссылки — ссылка на внешний веб-сайт, где предлагается скачать цифровой контент или приложение. Для загрузки приложения эта ссылка должна быть зарегистрирована и одобрена в консоли разработчика Google 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)

Ява 

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 перед повторной попыткой.

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

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

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

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