Управляйте своим каталогом продукции

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

Для продажи товаров в вашем приложении через платежную систему Google Play вам необходимо создать каталог со всеми товарами, которые вы хотите сделать доступными для покупки вашими пользователями. Это можно сделать через Play Console, или вы можете автоматизировать управление каталогом с помощью Google Play Developer API. Автоматизация поможет обеспечить постоянную актуальность вашего каталога и масштабируемость до больших каталогов, где ручная координация нецелесообразна. В этом руководстве вы узнаете, как использовать Play Developer API для создания и управления каталогом товаров для вашего приложения Play. Ознакомьтесь с нашим руководством по подготовке , чтобы узнать, как настроить Google Play Developer API для интеграции с вашей бэкэнд-системой.

API для управления каталогом

Чтобы узнать о различных типах товаров, которые можно продавать с помощью системы оплаты Google Play, прочитайте статью «Понимание типов товаров в приложениях и особенностей каталога» . Google предлагает два основных набора API для управления каталогом в 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 для управления каталогом продуктов следует учитывать несколько ограничений по квотам:

1. API для разработчиков Google Play организованы по категориям, называемым «корзинами», каждая из которых имеет свой лимит квоты в минуту. Для получения дополнительной информации см. раздел «Квоты» .
2. Для конечных точек модификации продукта также установлено ограничение в 7200 запросов в час. Это единое ограничение распространяется как на разовые продукты, так и на подписки, а также на все запросы на модификацию, включая создание, обновление, активацию и удаление. Вызовы методов пакетной модификации считаются одним запросом для этой квоты, независимо от количества отдельных запросов или их чувствительности к задержке.
3. Для модификаций, чувствительных к задержке, также установлен лимит в 7200 изменений в час. Для пакетных методов каждый вложенный запрос на модификацию учитывается отдельно для целей этой квоты. Эта квота имеет практическое значение только для пользователей пакетного API, выполняющих обновления, чувствительные к задержке, поскольку в других случаях квота 2 будет исчерпана раньше или одновременно с этой квотой.

Вот несколько наглядных примеров, позволяющих понять использование квот различными запросами:

• Один get запрос для получения одного элемента потребляет 1 токен квоты 1 и не потребляет токенов квот 2 и 3 (поскольку они касаются только конечных точек модификации).
• Пакетный get на получение до 100 элементов также будет расходовать 1 токен квоты 1 и не будет расходовать токены квот 2 и 3.
• Один запрос modification одного элемента потребляет 1 токен квоты 1 и 1 токен квоты 2. Если запрос чувствителен к задержке, он также потребляет 1 токен квоты 3. Поскольку квота C имеет тот же лимит, что и квота 2, это не имеет практического значения для пользователей, использующих только методы однократного изменения.
• Запрос на пакетную modification 100 элементов с допустимой задержкой будет расходовать 1 токен квоты 1 и 1 токен квоты 2. Такая настройка квоты должна обеспечить достаточный запас для обновления вашего каталога, но если ваш алгоритм не учитывает эту квоту и превышает ее, вы можете получить ошибку при каждом дополнительном вызове.
• Пакетный запрос modification 100 элементов, чувствительных к задержке, потребует 1 токен квоты 1, 1 токен квоты 2 и 100 токенов квоты 3.

Рекомендации по использованию API управления каталогом

Следуя этим рекомендациям, вы оптимизируете взаимодействие с API, обеспечивая бесперебойное и эффективное управление каталогом.

Отслеживайте свое использование

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

Оптимизация использования квот API

Оптимизация потребления трафика настоятельно рекомендуется для минимизации вероятности ошибок API. Для эффективной реализации этого мы рекомендуем следующее:

• Выберите правильную стратегию управления каталогом. После того, как вы разберетесь с квотой API, вам необходимо выбрать подходящую стратегию для вашего приложения, чтобы эффективно достичь целей управления каталогом.
• Совершайте только минимальное количество звонков, необходимое для отражения внесенных изменений.
• Не отправляйте избыточные или ненужные запросы на внесение изменений в API. Для этого может потребоваться вести журнал изменений в каталоге бэкэнда.
• Не превышайте почасовой лимит в 7200 запросов на изменение продукта. Возможно, вам потребуется создать процессы синхронизации, требующие внесения большого количества изменений в продукт за короткий промежуток времени (например, первоначальное создание каталога). Если вы ожидаете, что эти процессы превысят почасовой лимит, внедрите задержки по мере необходимости, чтобы снизить нагрузку до безопасного уровня. Рассмотрите возможность использования пакетных методов с обновлениями, устойчивыми к задержкам, для достижения более высокой пропускной способности.
• Заранее подготовьтесь к масштабированию. По мере роста вашего приложения вам может потребоваться увеличить использование API и различных конечных точек. Подробную информацию о том, как увеличить квоту при приближении к максимальному использованию, см. в документации Google Play Developer API по квотам .
• Стратегически планируйте ресурсоемкие процессы. Старайтесь планировать ресурсоемкие процессы работы с каталогом таким образом, чтобы они совпадали с пиковыми периодами использования. Например, можно избегать полной синхронизации каталога в часы пиковых продаж в течение недели.

Добавить логику обработки ошибок квот.

Независимо от того, насколько эффективно вы выстроили логику управления каталогом, необходимо обеспечить её устойчивость к неожиданным ограничениям квот, поскольку ежедневная квота распределяется между конечными точками, используемыми в независимых модулях вашей интеграции. Убедитесь, что вы включили обработку ошибок, связанных с ограничением квот, и реализовали соответствующие ожидания. Каждый вызов API разработчиков Google Play будет генерировать ответ. В случае сбоя вызова вы получите ответ, содержащий код состояния 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 в соответствии с последней информацией из каталога бэкэнда имеет преимущества для улучшения пользовательского опыта. Например:

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

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

стратегии синхронизации каталога

Конечные точки публикации API разработчиков Google Play позволяют обновлять каталог по мере внесения изменений. Иногда может потребоваться периодическая синхронизация, когда вы отправляете серию изменений в одном процессе. Каждый подход требует различных проектных решений. Каждая стратегия синхронизации лучше подходит для одних сценариев использования, чем для других, и у вас может быть набор потребностей, требующих обоих подходов, в зависимости от ситуации. Иногда вам может потребоваться обновить продукт, как только вы узнаете о новом изменении, например, для обработки срочного обновления продукта (т.е. необходимо как можно скорее исправить неправильную цену). В других случаях вы можете использовать периодическую фоновую синхронизацию, чтобы обеспечить постоянную согласованность каталогов в бэкэнде и 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 . Это позволит минимизировать время, необходимое для создания каталога в рамках квотных ограничений.

Для небольших каталогов подписок API разработчика Play предоставляет метод 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, могут возникнуть ситуации, когда он рассинхронизируется с каталогом в конфигурации ваших приложений в Play. Это может быть связано с экстренными изменениями каталога вручную в консоли, сбоем в вашей системе управления каталогом или, возможно, с потерей последних данных.

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

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

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

• Понимание моделей данных: Первый шаг — понять модели данных CMS для разработчиков и API для разработчиков Google Play. Это включает в себя знание различных типов данных, хранящихся в каждой системе, и того, как различные элементы данных соотносятся друг с другом.
• Определите правила сравнения: После того, как вы разберетесь с моделями данных, вам необходимо определить правила сравнения. Эти правила будут определять, как будут сравниваться данные в двух системах. Например, вы можете захотеть сопоставить идентификаторы продуктов и сравнить ключевые атрибуты подписки, а также связанные с ней базовые планы и предложения.
• Реализуйте алгоритм сравнения: После определения правил сравнения необходимо реализовать алгоритм сравнения. Этот алгоритм будет брать данные из двух систем и сравнивать их в соответствии с определенными вами правилами. Для получения данных каталога из Google Play можно использовать методы monetization.onetimeproducts.list , monetization.onetimeproducts.batchGet , inappproducts.list , inappproducts.batchGet , monetization.subscriptions.list и monetization.subscriptions.batchGet .
• Создание отчетов о различиях: Алгоритм сравнения создаст отчет о различиях. В этом отчете будут показаны различия между двумя системами.
• Устранение расхождений: После создания отчета о различиях необходимо устранить выявленные расхождения. Это может включать обновление данных в вашей CMS или обновление данных на стороне Google Play с использованием конечных точек управления каталогом через API для разработчиков, в зависимости от того, как вы обычно обновляете свой каталог. Для устранения расхождений в данных о товарах используйте конечные точки обновления, как описано в разделе «Обновления товаров».

амортизация продукта

API для разработчиков Google Play предоставляет следующие методы, которые помогут вам в устаревании ваших продуктов:

Для товаров, приобретаемых разово:

• monetization.onetimeproducts.delete
• monetization.onetimeproducts.batchDelete
• inappproducts.delete
• inappproducts.batchDelete

Для товаров по подписке:

• monetization.subscriptions.delete для подписок. Подписку нельзя удалить, если активирован хотя бы один базовый тарифный план.

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

• Создание по ошибке.
• Прекращение поддержки той или иной функции или услуги.

Мы рекомендуем включить устаревание товаров в вашу стратегию управления каталогом.