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

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

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

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

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

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

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

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

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

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

Проверить наличие

Для подтверждения доступности внешних предложений для текущего пользователя вызовите функцию isBillingProgramAvailableAsync .

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

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

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 Billing. Получить этот токен можно, вызвав API createBillingProgramReportingDetailsAsync . Новый токен должен быть сгенерирован непосредственно перед перенаправлением пользователя за пределы приложения для каждого внешнего предложения. Токены не должны кэшироваться между транзакциями.

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

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(context) {
      billingClient
        .createBillingProgramReportingDetails(params)
    }
  // Process the result

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

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

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

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

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

// 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, вызывая API разработчика Google Play из вашей административной панели. При отправке отчета о транзакции необходимо предоставить externalTransactionToken , полученный из API createBillingProgramReportingDetailsAsync . Если пользователь совершает несколько покупок, вы можете использовать один и тот же externalTransactionToken для отправки отчета о каждой покупке. Чтобы узнать, как отправлять отчеты о транзакциях, см. руководство по интеграции с административной панелью .

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

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

• ERROR : Это внутренняя ошибка. Не продолжайте транзакцию и не открывайте внешний веб-сайт. Повторите попытку, вызвав метод 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.

Протестируйте внешние предложения

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

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

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