Система выставления счетов Google Play — это сервис, позволяющий продавать цифровые продукты и контент в вашем Android-приложении. В майском релизе 2022 года мы изменили определение продуктов по подписке, и это влияет на то, как они продаются внутри приложения и управляются в вашей административной панели. Если вы впервые интегрируетесь с Google Play Billing, вы можете начать интеграцию, прочитав раздел «Подготовка» .
Если вы продавали подписки через Google Play Billing до мая 2022 года, важно понимать, как внедрять новые функции, сохраняя при этом существующие подписки.
Прежде всего, важно знать, что все ваши существующие подписки, приложения и интеграции с бэкэндом работают так же, как и до релиза в мае 2022 года . Вам не нужно вносить никаких немедленных изменений, и вы можете внедрять новые функции постепенно. Поддержка каждого крупного релиза библиотеки Google Play Billing Library осуществляется в течение двух лет после выпуска. Существующие интеграции с Google Play Developer API продолжают работать как и прежде.
Вот краткий обзор обновлений за май 2022 года:
- Новая консоль Google Play позволяет создавать и управлять подписками, базовыми тарифами и предложениями. Это касается как новых, так и перенесенных подписок.
- API для разработчиков Play содержит обновления, поддерживающие новые функции пользовательского интерфейса Google Play Console в формате API. В частности, появилась новая версия API для управления покупками подписок . Используйте этот API для проверки статуса подписки и управления покупками подписок.
- Новая версия 5 библиотеки Play Billing позволяет вашему приложению воспользоваться всеми новыми функциями подписки. Когда вы будете готовы обновиться до версии 5, следуйте инструкциям в руководстве по миграции .
Настройка подписок
Управление подписками через Google Play Console
Начиная с мая 2022 года, вы заметите некоторые изменения в консоли Google Play.
Теперь одна подписка может включать несколько базовых планов и предложений. Ранее созданные SKU подписок теперь отображаются в Play Console как новые объекты подписки, базового плана и предложения. Если вы еще этого не сделали, ознакомьтесь с разделом «Последние изменения в подписках в Play Console» для получения описания новых объектов, включая их функциональность и конфигурацию. Все ваши существующие продукты подписки отображаются в Google Play Console в этом новом формате. Каждый SKU теперь представлен объектом подписки, который содержит один базовый план и, если применимо, обратно совместимое предложение.
Поскольку в более старых интеграциях предполагалось, что каждая подписка будет включать одно предложение, представленное объектом SkuDetails , каждая подписка может иметь один обратно совместимый базовый план или предложение. Обратно совместимый базовый план или предложение возвращается как часть SKU для приложений, использующих устаревший метод querySkuDetailsAsync() . Для получения дополнительной информации о настройке и управлении обратно совместимыми предложениями см. раздел «Понимание подписок». Как только ваше приложение будет использовать только queryProductDetailsAsync() и как только старые версии вашего приложения перестанут совершать покупки, вам больше не потребуется использовать обратно совместимое предложение.
Управление подписками через API публикации подписок
API для разработчиков Play содержит новые функции для покупок по подписке. API для управления артикулами (SKU) inappproducts продолжает работать как и прежде, включая обработку товаров с разовой покупкой и подписок, поэтому вам не нужно вносить какие-либо изменения для поддержания интеграции.
Однако важно отметить, что Google Play Console использует только новые сущности подписок. Как только вы начнете редактировать свои подписки в Console, API inappproducts больше нельзя будет использовать для работы с подписками .
Если вы использовали API публикации до мая 2022 года, во избежание проблем, все существующие подписки теперь отображаются в консоли Google Play как доступные только для чтения. При попытке внести изменения может появиться предупреждение с объяснением этого ограничения. Прежде чем редактировать подписки в консоли, необходимо обновить интеграцию с бэкэндом, чтобы использовать новые конечные точки публикации подписок. Новые конечные точки monetization.subscriptions , monetization.subscriptions.baseplans и monetization.subscriptions.offers позволяют управлять всеми доступными базовыми планами и предложениями. В следующей таблице показано, как различные поля сопоставляются из сущности InAppProduct с новыми объектами в разделе monetization.subscriptions :
| В приложении | Подписка |
|---|---|
packageName | packageName |
sku | productId |
status | basePlans[0].state |
prices | basePlans[0].regionalConfigs.price |
listings | объявления |
defaultPrice | Нет эквивалента |
subscriptionPeriod | basePlans[0].autoRenewingBasePlanType.billingPeriodDuration |
trialPeriod | basePlans[0].offers[0].phases[0].regionalConfigs[0].free |
gracePeriod | basePlans[0].autoRenewingBasePlanType.gracePeriodDuration |
subscriptionTaxesAndComplianceSettings | taxAndComplianceSettings |
Это необходимое обновление API применяется только к API публикации (управление артикулами).
Изменения в библиотеке Play Billing
Для поддержки поэтапной миграции библиотека Play Billing включает все методы и объекты, доступные в предыдущих версиях. Объекты SkuDetails и функции, такие как querySkuDetailsAsync() по-прежнему существуют, поэтому вы можете обновить функциональность , не обновляя сразу существующий код подписок. Вы также можете контролировать, какие предложения доступны через эти методы, пометив их как обратно совместимые.
В дополнение к сохранению устаревших методов, Play Billing Library 5 теперь включает новый объект ProductDetails и соответствующий метод queryProductDetailsAsync() для обработки новых сущностей и функциональности. Существующие внутриигровые продукты (разовые покупки и расходные материалы) теперь также поддерживаются объектом ProductDetails .
Для подписки ProductDetails.getSubscriptionOfferDetails() возвращает список всех базовых планов и предложений, которые пользователь может приобрести. Это означает, что вы можете получить доступ ко всем базовым планам и предложениям, доступным для пользователя, независимо от обратной совместимости. getSubscriptionOfferDetails() возвращает null для продуктов, не являющихся подпиской. Для разовых покупок можно использовать getOneTimePurchaseOfferDetails() .
Библиотека Play Billing Library 5 также включает как новые, так и устаревшие методы запуска процесса покупки. Если объект BillingFlowParams передаваемый в BillingClient.launchBillingFlow() , настроен с использованием объекта SkuDetails , система извлекает информацию о предложении для продажи из обратно совместимого базового плана или предложения, соответствующего SKU. Если объект BillingFlowParams передаваемый в BillingClient.launchBillingFlow() , настроен с использованием объектов ProductDetailsParams , которые включают ProductDetails и String представляющую конкретный токен предложения для приобретаемого предложения, система затем использует эту информацию для идентификации продукта, приобретаемого пользователем.
queryPurchasesAsync() возвращает все покупки, совершенные пользователем. Чтобы указать запрошенный тип продукта, можно передать значение BillingClient.SkuType , как в более старых версиях, или объект QueryPurchasesParams , содержащий значение BillingClient.ProductType , представляющее новые сущности подписки.
Мы рекомендуем в ближайшее время обновить ваши приложения до версии 5 библиотеки, чтобы вы могли начать пользоваться преимуществами новых функций подписки.
Управление статусом подписки
В этом разделе описываются основные изменения в серверных компонентах интеграции с платежной системой Google Play, которые необходимо внести для миграции на версию 5.
Уведомления для разработчиков в режиме реального времени
Вскоре объект SubscriptionNotification больше не будет содержать subscriptionId . Если вы используете это поле для идентификации продукта подписки, вам следует обновить код, чтобы получать эту информацию из статуса подписки, используя purchases.subscriptionv2:get после получения уведомления. Каждый элемент SubscriptionPurchaseLineItem в коллекции lineItems , возвращаемый в составе статуса покупки, будет содержать соответствующий productId .
API для покупки подписок: получение статуса подписки
В предыдущих версиях API для покупки подписок можно было запросить статус подписки, используя purchases.subscriptions:get . Этот конечный пункт остался неизменным и продолжает работать для обратно совместимых покупок подписок. Этот конечный пункт не поддерживает никакие новые функции, выпущенные в мае 2022 года.
В новой версии API для покупки подписок используйте purchases.subscriptionsv2:get для получения статуса покупки подписки. Этот API совместим с перенесенными подписками, новыми подписками (как предоплаченными, так и автоматически продлеваемыми) и покупками всех типов. Вы можете использовать эту конечную точку для проверки статуса подписки при получении уведомлений. Возвращаемый объект SubscriptionPurchaseV2 содержит новые поля, но по-прежнему включает устаревшие данные, необходимые для дальнейшей поддержки существующих подписок.
Поля SubscriptionPurchaseV2 для предоплаченных тарифных планов
Добавлены новые поля для поддержки предоплаченных тарифных планов, которые продлеваются пользователем самостоятельно, а не автоматически. Все поля применяются к предоплаченным тарифным планам так же, как и к подпискам с автоматическим продлением, за исключением следующих случаев:
- [Новое поле] lineItems[0].prepaid_plan.allowExtendAfterTime : указывает, когда пользователю будет разрешено пополнить счет еще раз, чтобы продлить свой предоплаченный тарифный план, поскольку пользователю разрешено иметь только одно неиспользованное пополнение одновременно.
- [Новое поле] SubscriptionState : определяет состояние объекта подписки. Для предоплаченных тарифов это значение всегда равно
ACTIVE,PENDINGилиCANCELED. - lineItems[0].expiryTime : Это поле всегда присутствует для предоплаченных тарифов.
- paused_state_context : Это поле никогда не присутствует, поскольку предоплаченные тарифные планы не могут быть приостановлены.
- lineItems[0].auto_renewing_plan : Отсутствует для предоплаченных планов.
- canceled_state_context : Отсутствует для предоплаченных тарифов, поскольку это поле применяется только к пользователям, которые активно отменяют подписку.
- lineItems[0].productId : Это поле заменяет
subscriptionIdиз предыдущих версий.
Поля SubscriptionPurchaseV2 для повторяющихся подписок
В файле purchases.subscriptionv2 появились новые поля, предоставляющие более подробную информацию о новых объектах подписки. В следующей таблице показано, как поля из устаревшей конечной точки подписки сопоставляются с соответствующими полями в purchases.subscriptionv2 .
| Покупка подписки | SubscriptionPurchasV2 |
|---|---|
countryCode | regionCode |
orderId | latestOrderId |
| (Нет эквивалентного поля) | lineItems.offerPhase (определяет текущий этап: бесплатный пробный период, вводная цена, пропорциональное распределение, базовая цена) |
| (Нет эквивалентного поля) | lineItems (список объектов SubscriptionPurchaseLineItem ), представляющий товары, приобретенные при покупке. |
| (Нет эквивалентного поля) | lineItems.offerDetails.basePlanId |
| (Нет эквивалентного поля) | lineItems.offerDetails.offerId |
| (Нет эквивалентного поля) | lineItems.offerDetails.offerTags |
startTimeMillis | startTime |
expiryTimeMillis | lineItems.expiryTime (каждая подписка, приобретенная при покупке, имеет собственное expiryTime ) |
| (Нет эквивалентного поля) | subscriptionState (указывает состояние подписки ) |
| (Нет эквивалентного поля) | pausedStateContext (присутствует только в том случае, если статус подписки равен SUBSCRIPTION_STATE_PAUSED ) |
autoResumeTimeMillis | pausedStateContext.autoResumeTime |
| (Нет эквивалентного поля) | canceledStateContext (присутствует только в том случае, если статус подписки равен SUBSCRIPTION_STATE_CANCELED ) |
| (Нет эквивалентного поля) | testPurchase (доступно только при покупке лицензии для тестировщиков) |
autoRenewing | lineItems.autoRenewingPlan.autoRenewEnabled |
priceCurrenceCode , priceAmountMicros | lineItems.autoRenewingPlan.recurringPrice |
introductoryPriceInfo | lineItems.offerPhase.introductoryPriceЭту информацию также можно найти в offer к каждой из приобретенных подписок. |
| developerPayload | (Нет эквивалентного поля) полезная нагрузка разработчика устарела |
| paymentState | (Нет эквивалентного поля) Состояние платежа можно определить по subscriptionState :
|
cancelReason , userCancellationTimeMillis , cancelSurveyResult | canceledStateContext |
linkedPurchaseToken | linkedPurchaseToken (без изменений) |
purchaseType | Тест: посредством testPurchaseАкция: signupPromotion |
priceChange | lineItems.autoRenewingPlan.priceChangeDetails |
profileName , emailAddress , givenName , familyName , profileId | subscribeWithGoogleInfo |
acknowledgementState | acknowledgementState (no change) |
promotionType , promotionCode | signupPromotion |
externalAccountId , obfuscatedExternalAccountId , obfuscatedExteranlProfileId | externalAccountIdentifiers |
Другие функции управления подписками
Хотя purchases.subscriptions:get была обновлена до purchases.subscriptionsv2:get , остальные функции управления подписками для разработчиков пока остаются без изменений в конечной точке purchases.subscriptions , поэтому вы можете продолжать использовать purchases.subscriptions:acknowledge , purchases.subscriptions:cancel , purchases.subscriptions:defer , purchases.subscriptions:refund и purchases.subscriptions:revoke как и раньше.
API ценообразования
Используйте конечную точку monetization.convertRegionPrices для расчета региональных цен так же, как и через Play Console. Этот метод принимает одну цену в любой поддерживаемой Play валюте и возвращает конвертированные цены (включая стандартную ставку налога, если применимо) для всех регионов, где Google Play поддерживает покупки.