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

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

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

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

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

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

В следующем примере демонстрируется инициализация 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 Library. Этот токен можно получить, вызвав 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.
      }
});

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

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

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

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

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

Тестирование внешних предложений

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

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

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