Как интегрировать библиотеку Google Play Платежей в приложение

В этом документе описано, как интегрировать библиотеку Google Play Платежей в приложение, чтобы начать продавать товары.

Жизненный цикл покупки

Ниже описан типичный процесс разовой покупки или оформления подписки.

  1. Покажите пользователю, что он может купить.
  2. Запустите процесс покупки, чтобы пользователь мог подтвердить ее.
  3. Проверьте покупку на сервере.
  4. Предоставьте пользователю контент.
  5. Подтвердите доставку контента. Если товар расходуемый, выполните его потребление, чтобы пользователь мог купить его снова.

Подписки продлеваются автоматически, пока вы их не отмените. Подписка может иметь следующие статусы:

  • Активно. Пользователь имеет хорошую репутацию и доступ к подписке.
  • Отменена. Пользователь отменил подписку, но у него есть доступ к контенту до окончания срока действия.
  • Льготный период. У пользователя возникла проблема с оплатой, но у него по-прежнему есть доступ к контенту, пока Google пытается списать средства с помощью способа оплаты.
  • Приостановлена. У пользователя возникла проблема с оплатой, и у него больше нет доступа к контенту. Google пытается списать средства с помощью указанного способа оплаты.
  • Приостановлен. Пользователь приостановил доступ и не сможет пользоваться сервисом, пока не возобновит его.
  • Срок действия истек. Пользователь отменил подписку и потерял к ней доступ. По истечении срока действия подписки пользователь считается отказавшимся от нее.

Инициализация подключения к Google Play

Чтобы интегрировать платежную систему Google Play, сначала добавьте в приложение библиотеку Google Play Платежей и установите подключение.

Как добавить зависимость библиотеки Google Play Платежей

Добавьте зависимость библиотеки Google Play Платежей в файл build.gradle приложения, как показано ниже.

Яркий

dependencies {
    def billing_version = "9.1.0"

    implementation "com.android.billingclient:billing:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "9.1.0"

    implementation("com.android.billingclient:billing:$billing_version")
}

Если вы используете Kotlin, то модуль KTX библиотеки Google Play Платежей содержит расширения Kotlin и поддержку сопрограмм, которые позволяют писать идиоматический код Kotlin при использовании библиотеки Google Play Платежей. Чтобы включить эти расширения в проект, добавьте в файл build.gradle приложения следующую зависимость:

Яркий

dependencies {
    def billing_version = "9.1.0"

    implementation "com.android.billingclient:billing-ktx:$billing_version"
}

Kotlin

dependencies {
    val billing_version = "9.1.0"

    implementation("com.android.billingclient:billing-ktx:$billing_version")
}

Инициализация BillingClient

После добавления зависимости от библиотеки Google Play Платежей необходимо инициализировать экземпляр BillingClient. BillingClient – это основной интерфейс для связи между библиотекой Google Play Платежей и остальной частью приложения. BillingClient предоставляет удобные методы, как синхронные, так и асинхронные, для многих распространенных платежных операций. Обратите внимание на следующее:

  • Рекомендуется одновременно использовать только одно активное подключение BillingClient, чтобы избежать нескольких обратных вызовов PurchasesUpdatedListener для одного события.
  • Рекомендуется устанавливать подключение для BillingClient при запуске приложения или его переходе на передний план, чтобы обеспечить своевременную обработку покупок. Для этого можно использовать ActivityLifecycleCallbacks, зарегистрированный с помощью registerActivityLifecycleCallbacks, и прослушивать onActivityResumed, чтобы инициализировать подключение, когда вы впервые обнаружите, что действие возобновлено. Подробнее о том, почему следует придерживаться этой рекомендации, рассказывается в разделе Обработка покупок. Также не забудьте завершить подключение, когда приложение закрыто.

Чтобы создать BillingClient, используйте newBuilder. Вы можете передать любой контекст в newBuilder(), и BillingClient использует его, чтобы получить контекст приложения. Это означает, что вам не нужно беспокоиться об утечках памяти. Чтобы получать обновления о покупках, необходимо также вызвать setListener, передав ссылку на PurchasesUpdatedListener. Этот прослушиватель получает обновления обо всех покупках в вашем приложении.

Kotlin

private val purchasesUpdatedListener =
    PurchasesUpdatedListener { billingResult, purchases ->
        // To be implemented in a later section.
    }

private var billingClient = BillingClient.newBuilder(context)
    .setListener(purchasesUpdatedListener)
    // Configure other settings.
    .build()

Java

private PurchasesUpdatedListener purchasesUpdatedListener = new PurchasesUpdatedListener() {
  @Override
  public void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
      // To be implemented in a later section.
  }
};

private BillingClient billingClient = BillingClient.newBuilder(context)
  .setListener(purchasesUpdatedListener)
  // Configure other settings.
  .build();

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

После создания BillingClient необходимо установить связь с Google Play.

Чтобы подключиться к Google Play, вызовите startConnection. Процесс подключения является асинхронным, и вам необходимо реализовать BillingClientStateListener, чтобы получить обратный вызов после завершения настройки клиента и его готовности к дальнейшим запросам.

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

В примере ниже показано, как установить подключение и проверить, готово ли оно к использованию.

Kotlin

billingClient.startConnection(object : BillingClientStateListener {
    override fun onBillingSetupFinished(billingResult: BillingResult) {
        if (billingResult.responseCode == BillingResponseCode.OK) {
            // The BillingClient is ready. You can query purchases here.
        }
    }
    override fun onBillingServiceDisconnected() {
        // If automatic service reconnection is enabled, this can be left empty (no-op)
        // because the library handles retries. You can still use this for non-retry
        // tasks like logging or updating the UI to reflect a disconnected state.
        // Otherwise, try to restart the connection on the next request to
        // Google Play by calling the startConnection() method.
    }
})

Java

billingClient.startConnection(
        new BillingClientStateListener() {
            @Override
            public void onBillingSetupFinished(BillingResult billingResult) {
                if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                    // The BillingClient is ready. You can query purchases here.
                    // It's a good practice to query products after the connection is established.
                    queryProductDetails();
                }
            }

            @Override
            public void onBillingServiceDisconnected() {
                // Try to restart the connection on the next request to
                // Google Play by calling the startConnection() method.
                // This is automatically handled by the library when you call a method that requires a connection.
            }
        });

Автоматическое восстановление подключения

С появлением метода enableAutoServiceReconnection() в BillingClient.Builder версии 8.0.0 библиотека Play Платежей теперь может автоматически восстанавливать подключение к сервису, если вызов API выполняется, когда сервис отключен. Это может привести к уменьшению количества ответов SERVICE_DISCONNECTED, поскольку повторное подключение обрабатывается внутри системы до вызова API.

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

При создании экземпляра BillingClient используйте метод enableAutoServiceReconnection() в BillingClient.Builder, чтобы включить автоматическое повторное подключение.

Kotlin

val billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases(PendingPurchasesParams.newBuilder().enableOneTimeProducts().build())
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build()

Java

BillingClient billingClient = BillingClient.newBuilder(context)
    .setListener(listener)
    .enablePendingPurchases()
    .enableAutoServiceReconnection() // Add this line to enable reconnection
    .build();

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

После подключения к Google Play вы можете запрашивать доступные товары и показывать их пользователям.

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

Чтобы запросить сведения о контенте, оплачиваемом однократно, вызовите метод queryProductDetailsAsync. Этот метод может возвращать несколько предложений в зависимости от конфигурации контента для однократных покупок. Подробнее о нескольких способах покупки и специальных предложениях для контента, оплачиваемого однократно…

Чтобы обработать результат асинхронной операции, необходимо также указать прослушиватель, который реализует интерфейс ProductDetailsResponseListener. Затем вы можете переопределить метод onProductDetailsResponse, который уведомляет прослушиватель о завершении запроса, как показано в примере ниже.

Kotlin

val queryProductDetailsParams =
    QueryProductDetailsParams.newBuilder()
        .setProductList(
            listOf(
                Product.newBuilder()
                    .setProductId("product_id_example")
                    .setProductType(ProductType.SUBS)
                    .build()
            )
        )
        .build()

billingClient.queryProductDetailsAsync(queryProductDetailsParams) {
        billingResult,
        queryProductDetailsResult ->
    if (billingResult.responseCode == BillingResponseCode.OK) {
        for (productDetails in queryProductDetailsResult.productDetailsList) {
            // Process successfully retrieved product details here.
        }

        for (unfetchedProduct in queryProductDetailsResult.unfetchedProductList) {
            // Handle any unfetched products as appropriate.
        }
    }
}

Java

QueryProductDetailsParams queryProductDetailsParams =
QueryProductDetailsParams.newBuilder()
    .setProductList(
        ImmutableList.of(
            Product.newBuilder()
                .setProductId("product_id_example")
                .setProductType(ProductType.SUBS)
                .build()))
    .build();

billingClient.queryProductDetailsAsync(
queryProductDetailsParams,
new ProductDetailsResponseListener() {
    public void onProductDetailsResponse(BillingResult billingResult,
            QueryProductDetailsResult queryProductDetailsResult) {
        if (billingResult.getResponseCode() == BillingResponseCode.OK) {
           for (ProductDetails productDetails : queryProductDetailsResult.getProductDetailsList()) {
             // Process successfully retrieved product details here.
           }

           for (UnfetchedProduct unfetchedProduct : queryProductDetailsResult.getUnfetchedProductList()) {
             // Handle any unfetched products as appropriate.
           }
        }
    }
}
)

При запросе информации о товаре передайте экземпляр QueryProductDetailsParams, который указывает список строк идентификаторов товаров, созданных в Google Play Console, вместе с ProductType. В качестве ProductType можно указать ProductType.INAPP для контента, оплачиваемого однократно, или ProductType.SUBS для подписок.

Запросы с расширениями Kotlin

Если вы используете расширения Kotlin, то можете запросить информацию о контенте для однократных покупок, вызвав функцию расширения queryProductDetails().

queryProductDetails() использует сопрограммы Kotlin, поэтому вам не нужно определять отдельный прослушиватель. Вместо этого функция приостанавливается до завершения запроса, после чего вы можете обработать результат:

suspend fun processPurchases() {
    val productList = listOf(
        QueryProductDetailsParams.Product.newBuilder()
            .setProductId("product_id_example")
            .setProductType(BillingClient.ProductType.SUBS)
            .build()
    )
    val params = QueryProductDetailsParams.newBuilder()
    params.setProductList(productList)

    // leverage queryProductDetails Kotlin extension function
    val productDetailsResult = withContext(Dispatchers.IO) {
        billingClient.queryProductDetails(params.build())
    }

    // Process the result.
}

В редких случаях некоторые устройства не поддерживают ProductDetails и queryProductDetailsAsync(). Обычно это связано с устаревшими версиями сервисов Google Play. Чтобы обеспечить поддержку этого сценария, узнайте, как использовать функции обратной совместимости, в руководстве по переходу на библиотеку Play Платежей версии 7.

Обработка результата

Библиотека Google Play Платежей сохраняет результаты запроса в объекте QueryProductDetailsResult. QueryProductDetailsResult содержит List объектов ProductDetails. Затем вы можете вызвать различные методы для каждого объекта ProductDetails в списке, чтобы посмотреть информацию об успешно полученном контенте для однократных покупок, например его цену или описание. Чтобы посмотреть доступную информацию о товаре, ознакомьтесь со списком методов в классе ProductDetails.

QueryProductDetailsResult также содержит List объектов UnfetchedProduct. Затем вы можете запросить каждый UnfetchedProduct, чтобы получить код статуса, соответствующий причине сбоя извлечения. Чтобы посмотреть доступную информацию о товарах, которая не была получена, ознакомьтесь со списком методов в классе UnfetchedProduct.

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

Прежде чем предлагать подписку, убедитесь, что пользователь ещё не оформил ее. Также обратите внимание на следующее:

  • Для подписок метод queryProductDetailsAsync() возвращает информацию о товаре подписки и максимум 50 доступных пользователю специальных предложений на подписку. Если пользователь попытается приобрести специальное предложение, которое ему недоступно (например, если в приложении показывается устаревший список доступных специальных предложений), Google Play сообщит ему об этом и предложит приобрести основной план.

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

Запуск процесса покупки

Чтобы начать запрос о покупке из приложения, вызовите метод launchBillingFlow() из основного потока приложения. Этот метод принимает ссылку на объект BillingFlowParams, который содержит объект ProductDetails, полученный в результате вызова queryProductDetailsAsync. Чтобы создать объект BillingFlowParams, используйте класс BillingFlowParams.Builder.

Kotlin

// An activity reference from which the billing flow will be launched.
val activity : Activity = ...

val productDetailsParamsList = listOf(
    BillingFlowParams.ProductDetailsParams.newBuilder()
        // retrieve a value for productDetails by calling queryProductDetailsAsync()
        .setProductDetails(productDetails)
        // Get the offer token:
        // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
        // for a list of offers that are available to the user.
        // b. For subscriptions, call ProductDetails.getSubscriptionOfferDetails()
        // for a list of offers that are available to the user.
        .setOfferToken(selectedOfferToken)
        .build()
)

val billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build()

// Launch the billing flow
val billingResult = billingClient.launchBillingFlow(activity, billingFlowParams)

Java

// An activity reference from which the billing flow will be launched.
Activity activity = ...;

ImmutableList<BillingFlowParams.ProductDetailsParams> productDetailsParamsList =
    ImmutableList.of(
        BillingFlowParams.ProductDetailsParams.newBuilder()
             // retrieve a value for "productDetails" by calling queryProductDetailsAsync()
            .setProductDetails(productDetails)
            // Get the offer token:
            // a. For one-time products, call ProductDetails.getOneTimePurchaseOfferDetailsList()
            // for a list of offers that are available to the user.
            // b. For subscriptions, call ProductDetails.getSubscriptionOfferDetails()
            // for a list of offers that are available to the user.
            .setOfferToken(selectedOfferToken)
            .build()
    );

BillingFlowParams billingFlowParams = BillingFlowParams.newBuilder()
    .setProductDetailsParamsList(productDetailsParamsList)
    .build();

// Launch the billing flow
BillingResult billingResult = billingClient.launchBillingFlow(activity, billingFlowParams);

Метод launchBillingFlow() возвращает один из нескольких кодов ответа, перечисленных в BillingClient.BillingResponseCode. Обязательно проверьте этот результат, чтобы убедиться, что при запуске процесса покупки не возникло ошибок. BillingResponseCode OK указывает на успешный запуск.

При успешном вызове launchBillingFlow() система показывает экран покупки Google Play. На рисунке 1 показан экран покупки подписки.

На экране покупки в Google Play показана подписка, доступная для покупки.
Рисунок 1. На экране покупки в Google Play показана подписка, доступная для приобретения.

Google Play вызывает onPurchasesUpdated(), чтобы передать результат покупки слушателю, который реализует интерфейс PurchasesUpdatedListener. Прослушиватель указывается с помощью метода setListener() при инициализации клиента.

Чтобы обрабатывать возможные коды ответа, необходимо реализовать onPurchasesUpdated(). В примере ниже показано, как переопределить onPurchasesUpdated():

Kotlin

override fun onPurchasesUpdated(billingResult: BillingResult, purchases: List<Purchase>?) {
    if (billingResult.responseCode == BillingResponseCode.OK && purchases != null) {
        for (purchase in purchases) {
            // Process the purchase as described in the next section.
        }
    } else if (billingResult.responseCode == BillingResponseCode.USER_CANCELED) {
        // Handle an error caused by a user canceling the purchase flow.
    } else {
        // Handle any other error codes.
    }
}

Java

@Override
void onPurchasesUpdated(BillingResult billingResult, List<Purchase> purchases) {
  if (billingResult.getResponseCode() == BillingResponseCode.OK
      && purchases != null) {
      for (Purchase purchase : purchases) {
          // Process the purchase as described in the next section.
      }
  } else if (billingResult.getResponseCode() == BillingResponseCode.USER_CANCELED) {
      // Handle an error caused by a user canceling the purchase flow.
  } else {
      // Handle any other error codes.
  }
}

При успешной покупке появляется экран успешной покупки Google Play, похожий на рисунок 2.

Экран подтверждения покупки в Google Play.
Рисунок 2. экран Google Play об успешной покупке.

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

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

Укажите персональную цену

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

Экран покупки в Google Play, на котором указано, что цена была скорректирована для пользователя.
Рисунок 3. Экран покупки в Google Play, на котором указано, что цена была скорректирована для пользователя.

Вы должны ознакомиться со статьей можно найти в статье 6 (1) (ea) Директивы ЕС о защите прав потребителей 2011/83/ЕС, в которой дано определение персональной цены.

setIsOfferPersonalized() принимает логическое значение. Если true, в интерфейсе Google Play показывается сообщение о раскрытии информации. Если false, то в интерфейсе не будет раскрытия информации. Значение по умолчанию – false.

Дополнительную информацию можно найти в Справочном центре для потребителей.

Как прикрепить идентификаторы пользователей

При запуске процесса покупки приложение может прикрепить любые идентификаторы пользователя, совершающего покупку, с помощью obfuscatedAccountId или obfuscatedProfileId. Например, это может быть зашифрованная версия логина пользователя в вашей системе. Эти параметры помогают Google выявлять мошенничество. Кроме того, это поможет вам убедиться, что покупки приписываются правильному пользователю, как описано в разделе Предоставление прав пользователям.

Обнаружение и обработка покупок

Обнаружение и обработка покупки, описанные в этом разделе, применимы ко всем типам покупок, включая покупки вне приложения, например активацию промоакций.

Приложение обнаруживает новые покупки и завершенные незавершенные покупки одним из следующих способов:

  1. Когда метод onPurchasesUpdated вызывается в результате вызова метода launchBillingFlow (как описано в предыдущем разделе) или если приложение запущено с активным подключением к библиотеке Платежей, когда совершается покупка за пределами приложения или завершается незавершенная покупка. Например, участник семейной группы одобряет незавершенную покупку на другом устройстве.
  2. Когда приложение вызывает queryPurchasesAsync, чтобы запросить информацию о покупках пользователя.

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

Чтобы приложение обрабатывало все покупки, вызовите BillingClient.queryPurchasesAsync(). Рекомендуем делать это, когда приложение успешно устанавливает связь с библиотекой Google Play Платежей (например, при запуске или переходе на передний план, как описано в разделе Инициализация BillingClient). Для этого вызовите queryPurchasesAsync, когда получите успешный результат для onServiceConnected. Это особенно важно в следующих ситуациях:

  • Проблемы с сетью во время покупки. Пользователь может успешно совершить покупку и получить подтверждение от Google, но его устройство потеряет подключение к сети до того, как оно и ваше приложение получат уведомление о покупке через PurchasesUpdatedListener.
  • Несколько устройств. Пользователь может купить товар на одном устройстве, а затем ожидать, что он будет доступен и на другом.
  • Обработка покупок, совершенных за пределами приложения. Некоторые покупки, например активация промокодов, могут совершаться за пределами приложения.
  • Обработка изменений статуса покупки. Пользователь может завершить оплату незавершенной покупки, когда ваше приложение не запущено, и ожидать подтверждения покупки при его открытии.
  • Приостановленные подписки. Подписка может быть приостановлена в течение жизненного цикла. BillingClient.queryPurchasesAsync() возвращает приостановленные подписки, только если в QueryPurchasesParams.Builder задан параметр includeSuspendedSubscriptions. Приостановленные подписки не возвращаются в PurchasesUpdatedListener.

Когда приложение обнаружит новую или завершенную покупку, оно должно:

  • Подтвердите покупку.
  • Предоставьте пользователю контент за совершенные покупки.
  • Уведомить пользователя.
  • Уведомляйте Google о том, что ваше приложение обработало завершенные покупки.

Эти шаги подробно описаны в следующих разделах, а затем приведен раздел с кратким изложением всех шагов.

Подтвердите покупку

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

Предоставьте пользователю право на использование

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

Если вы добавили идентификаторы пользователей к покупке, как описано в разделе Добавление идентификаторов пользователей, вы можете получить и использовать их, чтобы связать покупку с нужным пользователем в вашей системе. Этот метод полезен при сверке покупок, когда ваше приложение могло потерять контекст о том, для какого пользователя предназначена покупка. Чтобы защитить пользователей от злоупотреблений, Google Play рекомендует проверять эти идентификаторы на защищенном сервере, прежде чем предоставлять права. Подробнее о том, как проверять покупки перед предоставлением прав… Обратите внимание, что у покупок, совершенных за пределами приложения, эти идентификаторы не будут заданы. В этом случае ваше приложение может либо предоставить право вошедшему в систему пользователю, либо предложить пользователю выбрать предпочтительный аккаунт.

Для предзаказов до момента выпуска покупка находится в состоянии PENDING. Предзаказ будет завершен в момент выпуска, а состояние изменится на PURCHASED без дополнительных действий.

Уведомление пользователя

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

  • Во время активных действий или кат-сцен сообщение может отвлекать пользователя. В этом случае вы должны уведомить пользователя после того, как действие часть закончена.
  • Во время обучения и настройки игры. Например, пользователь мог совершить покупку за пределами приложения до его установки. Рекомендуем уведомлять новых пользователей о бонусе сразу после того, как они откроют игру или во время первоначальной настройки. Если для предоставления права на контент пользователю необходимо создать аккаунт или войти в него, рекомендуем сообщить пользователю, какие шаги нужно выполнить, чтобы получить доступ к покупке. Это очень важно, поскольку если приложение не обработает покупку, то через три дня средства будут возвращены.

Для уведомления пользователя о покупке Google Play рекомендует следующие механизмы:

  • Показать диалоговое окно в приложении.
  • Доставлять сообщения в специальный раздел приложения и уведомлять пользователей о новых сообщениях в этом разделе.
  • Используйте уведомление ОС.

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

Уведомление Google о том, что покупка обработана

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

Расходные материалы

Если у вашего приложения есть защищенный сервер, для надежной обработки покупок рекомендуем использовать метод Purchases.products:consume. Убедитесь, что покупка ещё не использована. Для этого проверьте значение consumptionState, возвращаемое методом Purchases.products:get. Если у вашего приложения нет серверной части, используйте метод consumeAsync() из библиотеки Google Play Платежей. Оба метода выполняют требование подтверждения и указывают, что ваше приложение предоставило пользователю право на контент. Эти методы также позволяют вашему приложению сделать контент для однократных покупок, соответствующий входному токену покупки, доступным для повторной покупки. При использовании consumeAsync() также необходимо передать объект, реализующий интерфейс ConsumeResponseListener. Этот объект обрабатывает результат операции потребления. Вы можете переопределить метод onConsumeResponse(), который библиотека Google Play Платежей вызывает по завершении операции.

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

Kotlin

val consumeParams =
    ConsumeParams.newBuilder()
        .setPurchaseToken(purchase.getPurchaseToken())
        .build()
val consumeResult = withContext(Dispatchers.IO) {
    client.consumePurchase(consumeParams)
}

Java

ConsumeParams consumeParams =
        ConsumeParams.newBuilder().setPurchaseToken(purchase.getPurchaseToken()).build();

ConsumeResponseListener listener =
        (billingResult, purchaseToken) -> {
            if (billingResult.getResponseCode() == BillingResponseCode.OK) {
                // Handle the success of the consume operation.
            }
        };

billingClient.consumeAsync(consumeParams, listener);

Нерасходуемые товары

Если у вашего приложения есть защищенный сервер, для подтверждения покупок без потребления рекомендуем использовать Purchases.products:acknowledge. Убедитесь, что покупка не была подтверждена ранее. Для этого проверьте значение acknowledgementState, возвращаемое методом Purchases.products:get.

Если у вас только клиентское приложение, используйте метод BillingClient.acknowledgePurchase() из библиотеки Google Play Платежей. Перед подтверждением покупки приложение должно проверить, не была ли она уже подтверждена, с помощью метода isAcknowledged() из библиотеки Google Play Платежей.

В примере ниже показано, как подтвердить покупку с помощью библиотеки Google Play Платежей.

Kotlin

val client: BillingClient = billingClient
val acknowledgePurchaseParams = AcknowledgePurchaseParams.newBuilder()
    .setPurchaseToken(purchase.purchaseToken)
val ackPurchaseResult = withContext(Dispatchers.IO) {
    client.acknowledgePurchase(acknowledgePurchaseParams.build())
}

Java

if (purchase.getPurchaseState() == Purchase.PurchaseState.PURCHASED) {
    if (!purchase.isAcknowledged()) {
        AcknowledgePurchaseParams acknowledgePurchaseParams =
                AcknowledgePurchaseParams.newBuilder()
                        .setPurchaseToken(purchase.getPurchaseToken())
                        .build();
        billingClient.acknowledgePurchase(acknowledgePurchaseParams, (billingResult) -> {
            // Acknowledgment handled.
        });
    }
}

Подписки

Подписки обрабатываются так же, как и нерасходуемый контент. По возможности используйте метод Purchases.subscriptions.acknowledge из Google Play Developer API, чтобы подтверждать покупку через защищенный сервер. Убедитесь, что покупка не была подтверждена ранее. Для этого проверьте значение acknowledgementState в ресурсе покупки, полученном с помощью Purchases.subscriptions:get. В противном случае вы можете подтвердить подписку с помощью метода BillingClient.acknowledgePurchase() из библиотеки Google Play Платежей, проверив значение isAcknowledged(). Все первоначальные покупки подписок должны быть подтверждены. Продление подписки подтверждать не нужно. Подробнее о том, когда нужно подтверждать подписки, рассказывается в статье Продажа подписок.

Как обрабатывать отклоненные или невыполненные покупки

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

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

Вместо этого немедленно отмените отклоненные покупки и верните средства за них через серверную часть, используя Google Play Developer API.

  • Подписки. Вызовите purchases.subscriptionsv2.revoke с "fullRefund": {} в revocationContext. В этом случае подписка немедленно прекращается, доступ отзывается и инициируется полный возврат средств.
  • Контент для однократных покупок. Вызовите метод orders.refund с параметром revoke, заданным как true, чтобы немедленно вернуть средства за заказ и отозвать разрешение на доступ к контенту. При вызове этого метода необходимо передать идентификатор заказа, который можно получить с помощью Purchase.getOrderId() или purchases.productsv2.getproductpurchasev2. Никогда не вызывайте методы consumeAsync(), acknowledgePurchase(), Purchases.products:consume и Purchases.products:acknowledge для отклоненных покупок.
  • Поведение RTDN и Voided Purchases API. Отмена доступа к контенту и возврат средств, инициированные разработчиком (purchases.subscriptionsv2.revoke и orders.refund с revoke, для которого задано значение true), активируют уведомления для разработчиков в режиме реального времени и регистрируются в Voided Purchases API (purchases.voidedpurchases.list с полем ответа voidedSource, для которого задано значение 1 для разработчика):
    • Подписки. Отправляются уведомления SUBSCRIPTION_REVOKED и VoidedPurchaseNotification.
    • Контент для однократных покупок. Отправляет уведомление VoidedPurchaseNotification (и ONE_TIME_PRODUCT_CANCELED, если в Play Console настроено получение всех уведомлений о контенте для однократных покупок).
    • Если вызвать orders.refund, не задав для revoke значение true, средства за заказ будут возвращены без отзыва права доступа. При этом уведомление об отзыве или аннулировании покупки не будет отправлено. Подробнее о том, как управлять подписками и разовыми покупками…

Recap

Ниже приведено краткое описание этих шагов.

  1. Отправьте данные о покупке на защищенный сервер, чтобы проверить ее перед предоставлением доступа к контенту.

  2. Обновите хранилище прав, добавив в него покупку. Если покупка находится в состоянии PENDING, убедитесь, что право на контент помечено как ожидающее и пользователь ещё не получает преимуществ. Рекомендуется выполнять этот шаг на защищенном сервере. Его можно объединить с вызовом API к серверу на шаге 1.

  3. Уведомите пользователя, используя подходящие сообщения (при необходимости отложите уведомление, как описано выше).

  4. Уведомите Google о том, что покупка была обработана, выполнив действия, описанные в разделе "Обработка покупок".

Чтобы проверить, правильно ли вы выполнили эти шаги, следуйте руководству по тестированию.

Как обрабатывать транзакции в ожидании

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

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

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

Когда в приложении совершается новая покупка (через PurchasesUpdatedListener или в результате вызова queryPurchasesAsync), используйте метод getPurchaseState(), чтобы определить, имеет ли покупка статус PURCHASED или PENDING. Предоставлять право доступа следует, только если статус – PURCHASED.

Если ваше приложение запущено и у вас есть активное подключение к библиотеке Play Платежей, когда пользователь совершает покупку, снова вызывается метод PurchasesUpdatedListener, а PurchaseState теперь имеет значение PURCHASED. После этого приложение может обработать покупку стандартным способом, описанным в разделе Обнаружение и обработка покупок. Кроме того, в методе onResume() приложения необходимо вызвать queryPurchasesAsync(), чтобы обработать покупки, которые перешли в состояние PURCHASED, когда приложение не было запущено.

Когда статус покупки меняется с PENDING на PURCHASED, ваш клиент real_time_developer_notifications получает уведомление ONE_TIME_PRODUCT_PURCHASED или SUBSCRIPTION_PURCHASED. Если покупка отменена, вы получите уведомление ONE_TIME_PRODUCT_CANCELED или SUBSCRIPTION_PENDING_PURCHASE_CANCELED. Это может произойти, если клиент не завершит оплату в течение требуемого периода времени. Обратите внимание, что вы всегда можете использовать Google Play Developer API, чтобы проверить текущий статус покупки.

Как обрабатывать покупки нескольких товаров

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

Чтобы поддерживать покупки нескольких товаров, логика предоставления контента в приложении должна проверять количество товаров. Получить доступ к полю quantity можно с помощью одного из следующих API:

После того как вы добавите логику для обработки покупок нескольких товаров, вам нужно будет включить функцию покупки нескольких товаров для соответствующего товара на странице управления товарами, оплачиваемыми однократно, в Google Play Developer Console.

Запрос платежной конфигурации пользователя

getBillingConfigAsync() – страна, указанная в настройках Google Play.

Вы можете запросить платежную конфигурацию пользователя после создания BillingClient. В приведенном ниже фрагменте кода показано, как вызвать метод getBillingConfigAsync(). Обработайте ответ, реализовав метод BillingConfigResponseListener. Этот прослушиватель получает обновления для всех запросов конфигурации платежей, инициированных из вашего приложения.

Если возвращенный объект BillingResult не содержит ошибок, вы можете проверить поле countryCode в объекте BillingConfig, чтобы узнать страну пользователя в Google Play.

Kotlin

// Use the default GetBillingConfigParams.
val getBillingConfigParams = GetBillingConfigParams.newBuilder().build()
billingClient.getBillingConfigAsync(
    getBillingConfigParams,
    object : BillingConfigResponseListener {
        override fun onBillingConfigResponse(
            billingResult: BillingResult,
            billingConfig: BillingConfig?
        ) {
            if (billingResult.responseCode == BillingResponseCode.OK &&
                billingConfig != null
            ) {
                val countryCode = billingConfig.countryCode
                // ...
            } else {
                // Handle errors
            }
        }
    }
)

Java

GetBillingConfigParams getBillingConfigParams = GetBillingConfigParams.newBuilder().build();
billingClient.getBillingConfigAsync(
        getBillingConfigParams,
        (billingResult, billingConfig) -> {
            if (billingResult.getResponseCode() == BillingResponseCode.OK && billingConfig != null) {
                String countryCode = billingConfig.getCountryCode();
            } else {
                // TODO: Handle errors
            }
        });