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

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

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

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 часов.

Конфигурация квоты

При использовании API разработчика Play для управления каталогом продуктов вам следует знать о нескольких ограничениях квот:

  1. API Google Play Developer организованы по категориям, называемым сегментами, где каждый сегмент имеет свою собственную квоту в минуту. Подробнее см. в разделе «Квоты» .
  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 и различных конечных точек. Ознакомьтесь с документацией по квотам API для разработчиков Google Play, чтобы узнать, как увеличить квоту, когда вы приближаетесь к максимальному использованию.
  • Стратегически планируйте ресурсоёмкие процессы. Старайтесь планировать ресурсоёмкие процессы каталогизации в периоды пиковой нагрузки. Например, можно не проводить полную синхронизацию каталога в периоды пиковых продаж.

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

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

Реализация управления каталогами

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

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

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

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

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

Для небольших каталогов подписок API разработчика Play предоставляет метод monetization.subscriptions.create . Кроме того, подписки можно создавать с помощью метода monetization.subscriptions.patch с параметром allowMissing как описано в разделе «Обновления продукта».

Все описанные выше методы создают подписки вместе с их базовыми планами (предоставляемыми в объекте Subscription). Эти базовые планы изначально неактивны. Для управления статусом базовых планов можно использовать конечную точку monetization.subscriptions.basePlans , включая активацию базового плана для его доступности для покупки. Кроме того, конечная точка monetization.subscriptions.basePlans.offers позволяет создавать и управлять предложениями.

Обновления продукта

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

Обновление разовых продуктов

Для обновления существующих одноразовых продуктов вам доступны следующие методы.

  • monetization.onetimeproducts.batchUpdate
  • inappproducts.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. Это может быть связано с экстренным ручным изменением каталога в консоли, сбоем в системе управления каталогами или потерей последних данных.

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

Рассмотрение дифференциальной системы

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

  • Понимание моделей данных: Первый шаг — понять модели данных 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.subscriptions.delete для подписок. Подписку нельзя удалить, если активирован хотя бы один базовый план.

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

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

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