В этом руководстве рассказывается, как использовать Google Play Developer API для создания каталога товаров в приложении Google Play и управления им.
Чтобы продавать товары в приложении через платежную систему Google Play, необходимо создать каталог со всеми товарами, которые вы хотите сделать доступными для покупки пользователями. Это можно сделать в Play Console или с помощью Google Play Developer API. Автоматизация помогает поддерживать актуальность каталога и масштабировать его, когда ручная координация нецелесообразна. В этом руководстве рассказывается, как с помощью Play Developer API создать каталог товаров для приложения в Google Play и управлять им. Инструкции по настройке Google Play Developer API для интеграции с серверной частью вы найдете в руководстве Подготовка.
Catalog Management API
О том, какие типы товаров можно продавать через платежную систему Google Play, рассказывается в статье Типы контента для продажи и особенности настройки товаров в каталоге. Google предлагает два основных набора API для управления каталогом в Google Play, которые соответствуют двум основным категориям товаров:
- Контент для однократных покупок
- Подписки
Контент для однократных покупок
Для контента для однократных покупок (ранее – контент для продажи через приложение) используется объектная модель контента для однократных покупок, которая позволяет настраивать несколько способов покупки и специальных предложений. Объектная модель контента для однократных покупок дает вам больше возможностей для продажи товаров и упрощает управление ими. Существующий контент, продаваемый через приложение, будет перенесен в объектную модель контента для однократных покупок. Подробнее о переносе контента, продаваемого через приложение…
Конечные точки monetization.onetimeproducts и inappproducts позволяют управлять контентом для однократных покупок из серверной части. Это включает создание, обновление и удаление товаров, а также управление ценами и доступностью. В зависимости от того, как вы обрабатываете контент для однократных покупок, вы будете моделировать расходуемые товары (их можно покупать сколько угодно раз) или постоянные разрешения (их нельзя приобрести дважды одним и тем же пользователем). Вы можете сами решать, какие товары будут расходуемыми, а какие – нет.
Подписки
Конечная точка monetization.subscriptions позволяет управлять подписками на стороне сервера. Вы можете создавать, обновлять и удалять подписки, а также управлять их доступностью и ценами в разных регионах. Помимо конечной точки monetization.subscriptions, мы также предоставляем конечные точки monetization.subscriptions.basePlans и monetization.subscriptions.basePlans.offers, которые позволяют управлять основными планами и специальными предложениями.
Пакетные методы
Конечные точки onetimeproducts, inappproducts и monetization.subscriptions предоставляют ряд пакетных методов, которые позволяют одновременно получать до 100 объектов в одном приложении или управлять ими.
Пакетные методы, используемые с включенной допустимой задержкой, поддерживают более высокую пропускную способность и особенно полезны для разработчиков больших каталогов при первоначальном создании каталога или сверке каталогов.
Задержка распространения обновлений и пропускная способность
После создания или изменения товара конечные пользователи могут не сразу увидеть изменения на своих устройствах из-за задержек в сети или при обработке данных. По умолчанию все запросы на изменение товаров чувствительны к задержкам. Это означает, что они оптимизированы для быстрого распространения через внутренние системы и обычно отражаются на устройствах конечных пользователей в течение нескольких минут.
Однако количество таких запросов на изменение ограничено.
Если вам нужно создать или обновить много товаров (например, при первоначальном создании большого каталога), вы можете использовать пакетные методы с полем latencyTolerance, для которого задано значение PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Это значительно увеличит пропускную способность. Обновления, не требующие немедленного применения, будут установлены на устройства конечных пользователей в течение 24 часов.
Настройка квот
При использовании Play Developer API для управления каталогом товаров действуют следующие квоты:
- Google Play Developer API разделены на категории, называемые сегментами. Для каждого сегмента установлена своя поминутная квота. Подробнее о квотах…
- Для конечных точек изменения товаров также действует ограничение в 7200 запросов в час. Это ограничение распространяется на контент для однократных покупок и подписки, а также на все запросы на изменение, включая создание, обновление, активацию и удаление. Вызовы методов пакетного изменения считаются одним запросом для этой квоты, независимо от количества включенных отдельных запросов или их чувствительности к задержке.
- Для изменений, чувствительных к задержке, также действует ограничение в 7200 изменений в час. При использовании пакетных методов каждый вложенный запрос на изменение учитывается отдельно. Эта квота имеет практическое значение только для пользователей пакетного API, выполняющих обновления, чувствительные к задержкам, поскольку в других случаях квота 2 будет исчерпана раньше или одновременно с этой квотой.
Ниже приведены примеры, которые помогут вам понять, как расходуется квота при разных запросах.
- Один запрос
getна получение одного объекта будет использовать один токен из квоты 1 и ни одного токена из квот 2 и 3 (поскольку они относятся только к конечным точкам изменения). - Пакетный запрос
getна получение до 100 элементов также будет использовать один токен квоты 1 и ни одного токена квот 2 и 3. - Один запрос
modificationдля одного объекта будет использовать 1 токен квоты 1 и 1 токен квоты 2. Если запрос чувствителен к задержке, он также использует один токен из квоты 3. Поскольку квота C имеет тот же лимит, что и квота 2, она не имеет практического значения для пользователей, использующих только методы однократной модификации. - Пакетный запрос
modificationдля 100 объектов, нечувствительных к задержке, будет использовать один токен из квоты 1 и один токен из квоты 2. Этого должно быть достаточно, чтобы поддерживать каталог в актуальном состоянии. Если ваш алгоритм не учитывает квоту и превышает ее, вы можете получить ошибку за каждый дополнительный вызов. - Пакетный запрос
modificationдля 100 элементов, чувствительных к задержке, использует один токен из квоты 1, один токен из квоты 2 и 100 токенов из квоты 3.
Рекомендации по использованию Catalog Management API
Соблюдая эти рекомендации, вы сможете оптимизировать взаимодействие с API и обеспечить эффективное управление каталогом.
Как отслеживать использование API
Вы должны знать о процессах интенсивного использования. Например, в начале интеграции конечные точки управления каталогом, скорее всего, будут использовать больше квоты для создания полного начального каталога. Это может повлиять на использование других конечных точек, таких как API статуса покупки, если вы близки к общему лимиту. Вам необходимо отслеживать использование квот, чтобы не превышать их. Есть несколько способов отслеживать использование. Например, вы можете использовать панель управления квотами Google Cloud API или любой другой внутренний или сторонний инструмент мониторинга API по вашему выбору.
Оптимизируйте использование квоты API
Чтобы снизить вероятность ошибок API, настоятельно рекомендуется оптимизировать использование квот. Чтобы эффективно реализовать этот подход, рекомендуем сделать следующее:
- Выберите подходящую стратегию управления каталогом. Разобравшись с квотами API, выберите стратегию, которая позволит эффективно управлять каталогом.
- Выполняйте только минимальное количество вызовов, необходимое для внесения изменений.
- Не отправляйте в API избыточные или ненужные вызовы для изменения данных. Для этого может потребоваться вести журнал изменений в каталоге на сервере.
- Не превышайте часовой лимит на изменение товаров (7200 запросов). Вам может потребоваться создать процессы синхронизации, которые требуют внесения большого количества изменений в товары за короткий период времени (например, при первоначальном создании каталога). Если вы ожидаете, что эти процессы превысят часовой лимит, реализуйте задержки, чтобы снизить использование до безопасного уровня. Чтобы повысить пропускную способность, используйте пакетные методы с обновлениями, устойчивыми к задержкам.
- Заранее подготовьтесь к масштабированию. По мере роста приложения вам может потребоваться расширить использование API и различных конечных точек. Подробную информацию о том, как увеличить квоту, если вы приближаетесь к максимальному объему использования, можно найти в документации по квотам Google Play Developer API.
- Планируйте ресурсоемкие процессы. Попробуйте запланировать ресурсоемкие процессы каталога на периоды, когда нагрузка на него минимальна. Например, не запускайте полную синхронизацию каталога в часы пиковых продаж.
Добавьте логику обработки ошибок квоты
Независимо от того, насколько эффективно вы выстраиваете логику управления каталогом, вы должны сделать ее устойчивой к неожиданным ограничениям квот, учитывая, что ежедневная квота распределяется между конечными точками, используемыми в независимых модулях вашей интеграции. Убедитесь, что вы включили ошибки ограничения квот в обработку ошибок и реализовали соответствующие ожидания. Каждый вызов Google Play Developer API генерирует ответ. В случае сбоя вызова вы получите ответ об ошибке, который включает код статуса HTTP-ответа и объект errors, содержащий дополнительные сведения о домене ошибки и сообщение об отладке. Например, если вы превысите дневное ограничение, то можете увидеть ошибку, похожую на следующую:
{
"code" : 403,
"errors" : [ {
"domain" : "usageLimits",
"message" : "Daily Limit Exceeded. The quota will be reset at midnight Pacific Time (PT). You may monitor your quota usage and adjust limits in the API
Console: https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxxx",
"reason" : "dailyLimitExceeded",
"extendedHelp" : "https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/quotas?project=xxxxxx"
} ],
}
Реализация управления каталогом
Разработчики используют конечные точки публикации товаров Google Play Developer API, чтобы синхронизировать каталог между своим сервером и Google Play. Если каталог Google Play всегда будет содержать актуальную информацию из каталога вашего сервера, это улучшит пользовательский опыт. Пример:
- Вы сможете просматривать весь список доступных предложений и управлять тегами предложений и основных планов, чтобы влиять на соответствие требованиям и логику показа предложений.
- Вы можете проверить, какие цены и информация о товарах видят пользователи на разных платформах, и убедиться, что они совпадают.
- При обработке новых покупок у вас под рукой будут сведения о товарах, и вам не придется совершать дополнительные вызовы Google Play Developer API во время критических пользовательских процессов, что может привести к задержкам и сбоям.
При создании каталога товаров в Google Play необходимо учитывать определенные ограничения и особенности. После того как вы изучите эти ограничения и решите, как структурировать каталог, выберите стратегию синхронизации.
Стратегии синхронизации каталога
Конечные точки публикации Google Play Developer API позволяют обновлять каталог по мере необходимости. Иногда может потребоваться периодически обновлять данные, отправляя сразу несколько изменений. Каждый подход требует разных дизайнерских решений. Каждая стратегия синхронизации подходит для определенных сценариев использования, и в зависимости от ситуации вам могут потребоваться обе.
Иногда вам может потребоваться обновить информацию о товаре сразу же, как только вы узнаете о новых изменениях, например чтобы обработать срочное обновление товара (т.е. как можно скорее исправить неправильную цену). В других случаях можно использовать периодическую фоновую синхронизацию, чтобы обеспечить согласованность каталогов бэкенда и Google Play. Ниже приведены примеры использования разных стратегий управления каталогом.
Когда отправлять уведомления об изменениях в местном ассортименте
В идеале обновление должно происходить сразу после изменения каталога товаров в серверной части, чтобы минимизировать расхождения.
Этот тип обновлений подходит в следующих случаях:
- Вы должны следить за тем, чтобы информация о товарах всегда была актуальной.
- Вам нужно ежедневно вносить небольшие изменения в сведения о товарах.
- Вам нужно обновить продукты, которые уже производятся и продаются.
Этот подход проще в реализации и позволяет синхронизировать каталог с минимальным расхождением.
Когда использовать периодические обновления
Периодические обновления выполняются асинхронно с изменением товаров на вашем сервере. Они подходят в следующих случаях:
- Вам не нужно обновлять сведения о товарах в короткие сроки.
- Вам нужно запланировать массовые обновления или процессы сверки.
- У вас уже есть система управления контентом или каталогом, которая постоянно обновляет каталог.
Если у вас большой каталог, используйте пакетные методы с обновлениями, устойчивыми к задержкам, чтобы достичь максимальной пропускной способности.
Создайте каталог товаров
Если у вас большой каталог, вы можете автоматизировать его загрузку в Google Play. Для этого типа тяжелых процессов лучше всего подходит периодическая стратегия в сочетании с пакетными методами, устойчивыми к задержкам.
Как создать контент для однократных покупок
Для первоначального однократного создания каталога товаров рекомендуем использовать метод monetization.onetimeproducts.batchUpdate или inapp_products.insert, в котором для поля allowMissing задано значение true, а для поля latencyTolerance – PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Это позволит минимизировать время, необходимое для создания каталога в рамках квоты.
Как создать подписку
Для первоначального создания большого каталога подписок рекомендуем использовать метод monetization.subscriptions.batchUpdate с полем allowMissing, для которого задано значение true, и полем latencyTolerance со значением PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Это позволит минимизировать время, необходимое для создания каталога в пределах квоты.
Для небольших каталогов подписок в Play Developer API предусмотрен метод monetization.subscriptions.create.
Вы также можете создавать подписки с помощью метода monetization.subscriptions.patch с параметром allowMissing, как описано в разделе "Обновления товаров".
Все описанные выше методы создают подписки вместе с их основными планами (которые поставляются в объекте Subscription). Изначально эти основные планы неактивны. Чтобы управлять статусом основных планов, используйте конечную точку monetization.subscriptions.basePlans. С ее помощью можно в том числе активировать основной план, чтобы сделать его доступным для покупки. Кроме того, конечная точка monetization.subscriptions.basePlans.offers позволяет создавать специальные предложения и управлять ими.
Новости о продуктах
Ниже описаны способы, которые позволяют эффективно изменять существующие товары, чтобы они соответствовали вашим последним корректировкам.
Обновить контент для однократных покупок
Обновить существующий контент для однократных покупок можно следующими способами:
- monetization.onetimeproducts.batchUpdate
inappproducts.patch– конечная точка patch используется для частичного обновления ресурса. Это значит, что вы можете обновить только те поля, которые указаны в теле запроса. Конечная точка patch обычно используется, когда нужно обновить только несколько полей ресурса.inappproducts.update– конечная точка, которая используется для полного обновления ресурса. Это означает, что в теле запроса нужно передать весь объект ресурса. Конечная точка обновления обычно используется, когда нужно обновить все поля в ресурсе. Если параметруallowMissingприсвоено значениеtrue, а указанный идентификатор товара не существует, конечная точка вставит товар, а не выдаст ошибку.inappproducts.batchUpdate– это пакетная версия конечной точки обновления, которая позволяет изменять несколько товаров с помощью одного запроса. Используйте его вместе с полемlatencyTolerance, для которого задано значениеPRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT, чтобы повысить пропускную способность.
Обновление товаров по подписке
Чтобы обновить существующие подписки, используйте метод monetization.subscriptions.patch. Этот метод принимает следующие обязательные параметры:
packageName– название пакета приложения, к которому относится подписка.productId: уникальный идентификатор товара подписки.
regionsVersion– версия конфигурации региона.
Если вы не создаете новую подписку с помощью параметра allowMissing, необходимо указать параметр updateMask. Этот параметр представляет собой список полей, разделенный запятыми, которые нужно обновить.
Например, если вы хотите обновить только страницу подписки, укажите поле listings в параметре updateMask.
Вы можете использовать monetization.subscriptions.batchUpdate, чтобы обновлять несколько подписок одновременно.
Используйте его вместе с полем latencyTolerance, для которого задано значение PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT, чтобы повысить пропускную способность.
Чтобы активировать, деактивировать или удалить основной план, а также перевести подписчиков на его последнюю версию, используйте конечную точку monetization.subscriptions.basePlans.
Вы также можете обновить специальные предложения для основных планов с помощью метода monetization.subscriptions.basePlans.offers.patch.
Сверка каталога
Если вы используете систему управления каталогом или базу данных за пределами Google Play, то, независимо от того, как часто вы обновляете каталог Google Play, он может не совпадать с каталогом в конфигурации приложения в Google Play. Это может быть связано с экстренными изменениями каталога в консоли, сбоем в системе управления каталогом или потерей последних данных.
Чтобы избежать длительных расхождений, вы можете создать процесс сверки каталогов.
Особенности системы Diff
Рекомендуем создать систему, которая будет выявлять расхождения и согласовывать данные. При создании системы сравнения для синхронизации каталогов учитывайте следующее:
- Изучите модели данных. Сначала нужно понять, как устроены модели данных в CMS разработчика и Google Play Developer API. Это включает в себя знание различных типов данных, хранящихся в каждой системе, и того, как различные элементы данных сопоставляются друг с другом.
- Определите правила сравнения. После того как вы разберетесь с моделями данных, вам нужно будет определить правила сравнения. Эти правила определяют, как сравниваются данные в двух системах. Например, вы можете сопоставить идентификаторы товаров и сравнить ключевые атрибуты подписки и связанных с ней основных планов и специальных предложений.
- Реализуйте алгоритм сравнения. После того как вы определили правила сравнения, вам нужно реализовать алгоритм сравнения. Этот алгоритм возьмет данные из двух систем и сравнит их в соответствии с заданными вами правилами. Чтобы получить данные каталога из Google Play, используйте методы
monetization.onetimeproducts.list,monetization.onetimeproducts.batchGet,inappproducts.list,inappproducts.batchGet,monetization.subscriptions.listиmonetization.subscriptions.batchGet. - Создание отчетов о различиях. Алгоритм сравнения создаст отчет о различиях. В этом отчете будут показаны различия между двумя системами.
- Устраните расхождения. После создания отчета о различиях необходимо устранить расхождения. В зависимости от того, как вы обычно обновляете каталог, вам может потребоваться обновить данные в CMS или в Google Play с помощью конечных точек управления каталогом Developer API. Чтобы синхронизировать товары, используйте конечные точки обновления, как описано в разделе "Обновление товаров".
Прекращение поддержки продукта
В Google Play Developer API есть следующие методы, которые помогут вам прекратить поддержку контента:
Для контента для однократных покупок:
monetization.onetimeproducts.deletemonetization.onetimeproducts.batchDeleteinappproducts.deleteinappproducts.batchDelete
Для подписок:
monetization.subscriptions.deleteдля подписок. Подписку нельзя удалить, если активирован хотя бы один основной план.
Прекращение поддержки продукта может потребоваться в различных сценариях, например:
- Создание по ошибке.
- Прекращение работы функции или сервиса.
Рекомендуем включить прекращение поддержки товаров в стратегию управления каталогом.