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

В этом руководстве рассказывается, как интегрировать API, чтобы предлагать альтернативные платежные системы с выбором пользователя в приложении.

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

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

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

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

  • Чтобы предложить пользователю выбор платежной системы, вызовите новый метод enableUserChoiceBilling.
  • Вам нужно зарегистрировать UserChoiceBillingListener для обработки случаев, когда пользователь выбирает альтернативную платежную систему.

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

Kotlin

val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // Handle new Google Play purchase.
    }

val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Handle alternative billing choice.
    }

val billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
    @Override
    public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
        // Handle new Google Play purchase.
    }
};

private UserChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
        UserChoiceDetails userChoiceDetails) {
        // Handle new Google Play purchase.
    }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    .enablePendingPurchases()
    .enableUserChoiceBilling(userChoiceBillingListener)
    .build();

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

Показывать доступные товары

Вы можете показывать пользователю доступные продукты так же, как при интеграции с платежной системой Google Play. Когда пользователь увидит доступные для покупки товары и выберет один из них, запустите процесс выбора платежной системы, как описано в следующем разделе.

Как запустить сценарий оплаты с выбором платежной системы

Запустите процесс выбора платежной системы, вызвав функцию launchBillingFlow(). Это работает так же, как запуск процесса покупки с интеграцией платежной системы Google Play: вы предоставляете экземпляр ProductDetails и offerToken, соответствующие продукту и предложению, которые хочет приобрести пользователь. Если пользователь выбирает платежную систему Google Play, эта информация используется для продолжения процесса покупки.

Когда разработчики вызывают метод launchBillingFlow(), платежная система Google Play выполняет следующие проверки:

  • Система проверяет, относится ли страна, указанная в профиле Google Play пользователя, к странам, в которых поддерживается альтернативная платежная система с выбором пользователя (то есть к поддерживаемым странам). Если страна, указанная в настройках Google Play пользователя, поддерживается, Google Play проверяет, включена ли альтернативная платежная система, на основе конфигурации BillingClient.
    • Если вы включили альтернативную платежную систему с возможностью выбора пользователя, в процессе покупки будет показываться интерфейс выбора пользователя.
    • Если альтернативная платежная система с возможностью выбора пользователя не включена, в процессе покупки будет показываться стандартный интерфейс платежной системы Google Play без возможности выбора пользователя.
  • Если страна, выбранная пользователем в Google Play, не поддерживается, в процессе покупки будет показан стандартный интерфейс платежной системы Google Play без возможности выбора.

В аккаунте Google Play пользователя указана поддерживаемая страна.

Страна, указанная в аккаунте Google Play пользователя, не поддерживается

enableUserChoiceBilling вызывается во время настройки BillingClient

Пользователь видит интерфейс для выбора согласия

Пользователь видит стандартный интерфейс платежной системы Google Play

enableUserChoiceBilling не вызывается во время настройки BillingClient

Пользователь видит стандартный интерфейс платежной системы Google Play

Пользователь видит стандартный интерфейс платежной системы Google Play

Как обрабатывать выбор пользователя

Дальнейшие действия в процессе покупки зависят от того, какую платежную систему выбрал пользователь: платежную систему Google Play или альтернативную платежную систему.

Когда пользователь выбирает альтернативную платежную систему

Если пользователь выбирает альтернативную платежную систему, Google Play вызывает метод UserChoiceBillingListener, чтобы уведомить приложение о необходимости запустить процесс покупки в этой системе. В частности, вызывается метод userSelectedAlternativeBilling().

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

UserChoiceBillingListener должен выполнить следующие действия:

  • Получите информацию о товаре или товарах, которые покупает пользователь, чтобы показать их в процессе покупки в альтернативной платежной системе.
  • Сохраните строку, полученную в качестве токена внешней транзакции, и отправьте ее на свой сервер. Он используется для передачи в Google Play информации о внешней транзакции, если пользователь совершит покупку.
  • Запустите альтернативный процесс покупки.

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

В примере ниже показано, как реализовать UserChoiceBillingListener:

Kotlin

private val userChoiceBillingListener =
    UserChoiceBillingListener { userChoiceDetails ->
        // Get the products being purchased by the user.
        val products = userChoiceDetails.products

        // Send external transaction token to developer backend server
        // this devBackend object is for demonstration purposes,
        // developers can implement this step however best fits their
        // app to backend communication.
        DevBackend.sendExternalTransactionStarted(
            userChoiceDetails.externalTransactionToken,
            user
        )

        // Launch alternative billing
        // ...
        // The developer backend handles reporting the transaction
        // to Google Play's backend once the alternative billing
        // purchase is completed.
    }

Java

private userChoiceBillingListener userChoiceBillingListener = new UserChoiceBillingListener() {
    @Override
    public void userSelectedAlternativeBilling(
           UserChoiceDetails userChoiceDetails) {
       // Get the products being purchased by the user.
       List<Product> products =
              userChoiceDetails.getProducts();

       // Send external transaction token to developer backend server
       // this devBackend object is for demonstration purposes,
       // developers can implement this step however best fits their
       // app to backend communication.
       devBackend.sendExternalTransactionStarted(
              userChoiceDetails.getExternalTransactionToken(),
              user
       );

       // Launch alternative billing
       // ...
       // The developer backend handles reporting the transaction
       // to Google Play's backend once the alternative billing
       // purchase is completed.
    }
};

Когда пользователь выбирает платежную систему Google Play

Если пользователь выберет платежную систему Google Play, он сможет совершить покупку через нее.

  • Чтобы узнать больше о том, как обрабатывать новые покупки в приложении через платежную систему Google Play, ознакомьтесь с разделом Обработка покупок в руководстве по интеграции библиотеки.
  • Дополнительную информацию о покупке подписок можно найти в разделе Новые подписки руководства по управлению подписками.

Как обрабатывать изменения в подписке

Если разработчик предлагает пользователям альтернативную платежную систему, то покупки должны обрабатываться через платежную систему Google Play или регистрироваться с помощью externalTransactionId в зависимости от выбора пользователя. Изменения в существующие подписки, оформленные через выбор пользователя, можно вносить через ту же платежную систему до истечения срока действия подписки.

В этом разделе описано, как обрабатывать некоторые распространенные сценарии изменения подписки.

Как перейти на управляемый домен

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

Дополнения, которые зависят от существующей подписки, используют тот же способ оплаты и имеют одинаковую периодичность списания средств, считаются обновлениями. Для других дополнений пользователи должны иметь возможность выбирать платежную систему. Инициируйте новый процесс покупки с помощью launchBillingFlow(), как описано в разделе Запуск процесса выбора платежной системы.

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

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

Для этого вызывайте launchBillingFlow(), когда пользователь запрашивает переход на более или менее дорогую версию. Вместо того чтобы указывать объект SubscriptionUpdateParams в параметрах, используйте setOriginalExternalTransactionId, предоставив внешний идентификатор транзакции для исходной покупки. В этом случае экран выбора платежной системы не показывается, поскольку выбор пользователя при первоначальной покупке сохраняется при переходе на более дорогой или дешевый тариф. В этом случае вызов launchBillingFlow() создает новый внешний токен транзакции, который можно получить из обратного вызова.

Kotlin

// The external transaction ID from the current
// alternative billing subscription.
val externalTransactionId = "your_external_transaction_id"

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(
        listOf(
            BillingFlowParams.ProductDetailsParams.newBuilder()
                // Fetched using queryProductDetailsAsync.
                .setProductDetails(productDetailsNewPlan)
                // offerIdToken can be found in
                // ProductDetails=>SubscriptionOfferDetails.
                .setOfferToken(offerTokenNewPlan)
                .build()
        )
    )
    .setSubscriptionUpdateParams(
        BillingFlowParams.SubscriptionUpdateParams.newBuilder()
            .setOriginalExternalTransactionId(externalTransactionId)
            .build()
    )
    .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

Java

// The external transaction ID from the current
// alternative billing subscription.
String externalTransactionId = //... ;

BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync.
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails
                    .setOfferToken(offerTokenNewPlan)
                    .build()
                )
            )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                .setOriginalExternalTransactionId(externalTransactionId)
                .build()
            )
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

// When the user selects the alternative billing flow,
// the UserChoiceBillingListener is triggered.

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

Подписки, оформленные через платежную систему Google Play

Аналогично, если пользователь оформил текущую подписку через платежную систему Google Play после того, как ему был предоставлен выбор, ему нужно показывать процесс перехода на более дорогой или дешевый тарифный план в платежной системе Google Play. Ниже описано, как запустить процесс покупки для перехода на более дорогой или дешевый тарифный план через платежную систему Google Play.

  1. Укажите offerToken выбранного предложения для нового плана:

    Kotlin

    val offerTokenNewPlan = productDetailsNewPlan.getSubscriptionOfferDetails()
    ?.getOrNull(selectedOfferIndex)
    ?.offerToken
    ?: ""

    Java

    String offerTokenNewPlan = productDetailsNewPlan
        .getSubscriptionOfferDetails(selectedOfferIndex)
        .getOfferToken();

  2. Отправьте в платежную систему Google Play правильную информацию для обработки новой покупки, в том числе токен покупки существующей подписки:

    Kotlin

    val billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            listOf(
                BillingFlowParams.ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    .setSubscriptionProductReplacementParams(
                        SubscriptionProductReplacementParams.newBuilder()
                            .setReplacementMode(
                                SubscriptionProductReplacementParams.ReplacementMode.CHARGE_FULL_PRICE
                            )
                            .setOldProductId("old_product_id")
                            .build()
                    )
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
            )
        )
        .setSubscriptionUpdateParams(
            BillingFlowParams.SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .build()
        )
        .build()

val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

    Java

    BillingFlowParams billingFlowParams =
    BillingFlowParams.newBuilder()
        .setProductDetailsParamsList(
            ImmutableList.of(
                ProductDetailsParams.newBuilder()
                    // Fetched using queryProductDetailsAsync
                    .setProductDetails(productDetailsNewPlan)
                    // offerIdToken can be found in
                    // ProductDetails=>SubscriptionOfferDetails.
                    .setOfferToken(offerTokenNewPlan)
                    .build()
            )
        )
        .setSubscriptionUpdateParams(
            SubscriptionUpdateParams.newBuilder()
                // purchaseToken can be found in
                // Purchase#getPurchaseToken
                .setOldPurchaseToken(oldToken)
                .setReplaceProrationMode(BillingFlowParams.ProrationMode.IMMEDIATE_AND_CHARGE_FULL_PRICE)
                .build()
        )
        .build();

BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Покупка будет совершена через платежную систему Google Play, а ваше приложение получит вызов PurchasesUpdatedListener.onPurchaseUpdated с результатом покупки. Если покупка прошла успешно, метод onPurchaseUpdated() также получает информацию о ней, а ваш сервер – уведомление разработчика в реальном времени SUBSCRIPTION_PURCHASED. При получении статуса новой покупки атрибут linkedPurchaseToken ссылается на старую покупку подписки, поэтому вы можете отменить ее.

Отмена и восстановление подписки

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

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

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

Если у вас есть внешний идентификатор транзакции для отмененной подписки, вызывать метод launchBillingFlow() для восстановления подписки не нужно, поэтому его не следует использовать для активации такого типа. Если пользователь восстановит подписку, пока ещё действует отмененная, транзакция не произойдет. Вы можете продолжать отправлять отчеты о продлениях, когда закончится текущий цикл и произойдет следующее продление. В том числе это относится к случаям, когда пользователь получает кредит или специальную цену продления в рамках восстановления (например, промоакцию, чтобы побудить пользователя продолжить подписку).

Подписки, оформленные через платежную систему Google Play

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

Вы также можете запустить восстановление в платежной системе Google Play из приложения, вызвав метод launchBillingFlow(). Инструкции приведены в разделе До истечения срока подписки (в приложении). Если пользователь прошел процедуру выбора пользователя для исходной покупки (которая была отменена, но все ещё активна), система автоматически обнаружит его выбор и покажет пользовательский интерфейс для восстановления этих покупок. Пользователю будет предложено подтвердить повторную покупку подписки через Google Play, но ему не нужно будет снова проходить процедуру выбора. В этом случае для пользователя выпускается новый токен покупки. Ваш сервер получает уведомление для разработчиков в режиме реального времени SUBSCRIPTION_PURCHASED, а значение linkedPurchaseToken для нового статуса покупки устанавливается так же, как при переходе на более дорогой или дешевый тарифный план, с использованием старого токена покупки для отмененной подписки.

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

Если срок действия подписки истек (из-за отмены или отклонения платежа без возможности восстановления), пользователь должен оформить ее заново, чтобы возобновить доступ к контенту.

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

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

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

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

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