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

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

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

Добавьте зависимость библиотеки Play Платежей в приложение для Android. Чтобы использовать API для альтернативных платежных систем, вам понадобится версия 6.1 или более новая.

Как подключить Google Play

Первые шаги интеграции такие же, как описано в руководстве по интеграции Google Play Платежей, но при инициализации BillingClient есть несколько отличий:

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

В примере ниже показано, как инициализировать BillingClient с этими изменениями:

var billingClient = BillingClient.newBuilder(context)
    .enableAlternativeBillingOnly()
    .build()
AlternativeBillingWithoutUserChoiceInApp.kt

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

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

Проверка доступности

Чтобы проверить, доступна ли в приложении только альтернативная платежная система, вызовите метод isAlternativeBillingOnlyAvailableAsync.

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

billingClient.isAlternativeBillingOnlyAvailableAsync(object :
    AlternativeBillingOnlyAvailabilityListener {
    override fun onAlternativeBillingOnlyAvailabilityResponse(
        billingResult: BillingResult
    ) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors,
            // handling alternative billing only being unavailable, etc.
            return
        }

        // Alternative billing only is available. Continue with steps in
        // the guide.
    }
})
AlternativeBillingWithoutUserChoiceInApp.kt

billingClient.isAlternativeBillingOnlyAvailable(
    new AlternativeBillingOnlyAvailabilityListener() {
        @Override
        public void onAlternativeBillingOnlyAvailabilityResponse(
            BillingResult billingResult) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                 // Handle failures such as retrying due to network errors,
                 // handling alternative billing only being unavailable,
                 // etc.
                return;
            }

            // Alternative billing only is available. Continue with steps in
            // the guide.
        }
    });

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

Если вы хотите интегрировать только альтернативную платежную систему, в приложении должен быть экран с информацией о том, что платежи не будут обрабатываться через Google Play. Каждый раз перед тем, как начать альтернативный процесс оплаты, пользователям необходимо показывать информационный экран. Для этого нужно вызывать API showAlternativeBillingOnlyInformationDialog. Если пользователь уже подтвердил диалоговое окно, использование этого API обычно не приводит к повторному показу диалогового окна. Диалоговое окно может быть показано пользователю снова, например если он очистит кеш на своем устройстве.

// An activity reference from which the alternative billing only information
// dialog will be launched.
val activity: Activity = this.activity

val listener: AlternativeBillingOnlyInformationDialogListener =
    AlternativeBillingOnlyInformationDialogListener { billingResult ->
        // check billingResult
    }

val billingResult =
    billingClient.showAlternativeBillingOnlyInformationDialog(
        activity,
        listener
    )
AlternativeBillingWithoutUserChoiceInApp.kt

// An activity reference from which the alternative billing only information
// dialog will be launched.
Activity activity = ...;

AlternativeBillingOnlyInformationDialogListener listener =
    new AlternativeBillingOnlyInformationDialogListener() {
        @Override
        public void onAlternativeBillingOnlyInformationDialogResponse(
            BillingResult billingResult) {
                // check billingResult
            }
    };

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

Если этот метод возвращает BillingResponseCode.OK, приложение может продолжить транзакцию. В случае BillingResponseCode.USER_CANCELED ваше приложение должно вызвать showAlternativeBillingOnlyInformationDialog, чтобы снова показать пользователю диалоговое окно. О том, как быть с другими кодами ответа, читайте в разделе об обработке ответов.

Как сообщать о транзакциях в Google Play

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

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(object :
    AlternativeBillingOnlyReportingDetailsListener {
    override fun onAlternativeBillingOnlyTokenResponse(
        billingResult: BillingResult,
        alternativeBillingOnlyReportingDetails: AlternativeBillingOnlyReportingDetails?
    ) {
        if (billingResult.responseCode != BillingResponseCode.OK) {
            // Handle failures such as retrying due to network errors.
            return
        }

        val externalTransactionToken =
            alternativeBillingOnlyReportingDetails?.externalTransactionToken

        // Send transaction token to backend and report to Google Play.
    }
})
AlternativeBillingWithoutUserChoiceInApp.kt

billingClient.createAlternativeBillingOnlyReportingDetailsAsync(
    new AlternativeBillingOnlyReportingDetailsListener() {
        @Override
        public void onAlternativeBillingOnlyTokenResponse(
            BillingResult billingResult,
            @Nullable AlternativeBillingOnlyReportingDetails
                alternativeBillingOnlyReportingDetails) {
            if (billingResult.getResponseCode() != BillingResponseCode.OK) {
                // Handle failures such as retrying due to network errors.
                return;
            }

            String transactionToken =
                alternativeBillingOnlyReportingDetails
                .getExternalTransactionToken();

            // Send transaction token to backend and report to Google Play.
        }
    });

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

Указанные выше методы isAlternativeBillingOnlyAvailableAsync(), showAlternativeBillingOnlyInformationDialog() и createAlternativeBillingOnlyReportingDetailsAsync() могут возвращать ответы, отличные от BillingResponseCode.OK, в случае ошибок. Ниже описаны рекомендуемые способы обработки ошибок.

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

Как протестировать альтернативную платежную систему

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

Дальнейшие действия

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