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

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

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

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

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

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

• Вам нужно вызвать новый метод, чтобы указать, что вы хотите использовать внешние предложения: enableExternalOffer .

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

var billingClient = BillingClient.newBuilder(context)
  .enableExternalOffer()
  .build()

private BillingClient billingClient = BillingClient.newBuilder(context)
    .enableExternalOffer()
    .build();

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

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

Ваше приложение должно подтвердить доступность внешних предложений, вызвав isExternalOfferAvailableAsync .

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

billingClient.isExternalOfferAvailableAsync(
  object : ExternalOfferAvailabilityListener {
    override fun onExternalOfferAvailabilityResponse(
      billingResult: BillingResult) {
        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.isExternalOfferAvailableAsync(
  new ExternalOfferAvailabilityListener() {
    @Override
    public void onExternalOfferAvailabilityResponse(
      BillingResult billingResult) {
        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 внешних предложений. Это можно сделать, вызвав API createExternalOfferReportingDetailsAsync . Этот токен должен быть сгенерирован непосредственно перед тем, как пользователь будет направлен за пределы приложения. Его никогда не следует кэшировать, а новый должен создаваться каждый раз, когда пользователь выходит за пределы приложения.

billingClient.createExternalOfferReportingDetailsAsync(
  object : ExternalOfferReportingDetailsListener {
    override fun onExternalOfferReportingDetailsResponse(
      billingResult: BillingResult,
      externalOfferReportingDetails: ExternalOfferReportingDetails?) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }
        val externalTransactionToken =
            externalOfferReportingDetails?.externalTransactionToken
        // Persist the transaction token locally. Pass it to the external
        // website when showExternalOfferInformationDialog is called.
    }
})

billingClient.createExternalOfferReportingDetailsAsync(
  new ExternalOfferReportingDetailsListener() {
    @Override
    public void onExternalOfferReportingDetailsResponse(
      BillingResult billingResult,
      @Nullable ExternalOfferReportingDetails
        externalOfferReportingDetails) {
        if (billingResult.getResponseCode() != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return;
        }

        String transactionToken =
          externalOfferReportingDetails.getExternalTransactionToken();

        // Persist the external transaction token locally. Pass it to the
        // external website when showExternalOfferInformationDialog is
        // called.
      }
});

Информационный диалог для пользователей

Для интеграции с внешними предложениями ваше подходящее приложение должно отображать информационный экран, который поможет пользователям понять, что их собираются перенаправить за пределы приложения на внешний веб-сайт. Информационный экран необходимо показывать пользователям путем вызова API showExternalOfferInformationDialog перед каждой ссылкой на внешнее предложение.

// An activity reference from which the external offers information dialog
// will be launched.
val activity : Activity = ...;

val listener : ExternalOfferInformationDialogListener =
  ExternalOfferInformationDialogListener {
      override fun onExternalOfferInformationDialogResponse(
        billingResult: BillingResult){
        // Check billingResult
    }
}

val billingResult = billingClient.showExternalOfferInformationDialog(
  activity, listener)

// An activity reference from which the external offers information dialog
// will be launched.
Activity activity = ...;

ExternalOfferInformationDialogListener listener =
  new ExternalOfferInformationDialogListener() {
    @Override
    public void onExternalOfferInformationDialogResponse(
      BillingResult billingResult) {
        if (billingResult.responseCode !=  BillingResponseCode.OK) {
          // Handle failures such as retrying due to network errors.
        }
        // Open the external website, passing along the external transaction
        // token as a URL parameter. If the user purchases an item, be sure
        // to report the transaction to Google Play.
      }
}

BillingResult billingResult =
  billingClient.showExternalOfferInformationDialog(activity, listener);

Если этот метод возвращает BillingResponseCode.OK , ваше приложение может перенаправить пользователя на внешний веб-сайт. Если метод возвращает BillingResponseCode.USER_CANCELED , ваше приложение не должно продолжать открывать веб-сайт.

Сообщайте о транзакциях в Google Play

Обо всех внешних транзакциях необходимо сообщать в Google Play, вызывая API разработчика Google Play со своей серверной части. О внешних транзакциях необходимо сообщать при предоставлении externalTransactionToken полученного с помощью API createExternalOfferReportingDetailsAsync . Если пользователь совершает несколько покупок, вы можете использовать один и тот же externalTransactionToken для отчета о каждой покупке. Чтобы узнать, как сообщить о транзакции, см. руководство по интеграции с серверной частью .

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

При возникновении ошибки методы isExternalOfferAvailableAsync , createExternalOfferReportingDetailsAsync и showExternalOfferInformationDialog могут возвращать ответы, отличные от BillingResponseCode.OK . Рассмотрите возможность обработки этих кодов ответа следующим образом:

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

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

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

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

Завершив интеграцию в приложении, вы готовы интегрировать свою серверную часть .