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

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

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

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

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

  • Одноразовые продукты
  • Продукты по подписке

Одноразовые продукты

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

Продукты по подписке

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

Пакетные методы

Конечные точки inappproducts и monetization.subscriptions предоставляют ряд пакетных методов, которые позволяют получать или управлять до 100 сущностями в одном приложении одновременно.

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

Задержка распространения обновлений в зависимости от пропускной способности

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

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

Существует несколько ограничений квот, о которых следует знать при использовании Play Developer API для управления каталогом продуктов:

  1. API-интерфейсы разработчика Google Play имеют ограничение по умолчанию в 200 000 запросов в день. Это ограничение квоты применяется к агрегированию использования во всех конечных точках, включая API управления каталогом.
  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. Существует несколько способов мониторинга использования. Например, вы можете использовать панель квот Google Cloud API или любой другой собственный или сторонний инструмент мониторинга 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"
  } ],
}

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

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

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

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

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

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

Когда отправлять обновления при изменении локального каталога

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

Этот тип обновлений является хорошим вариантом, если:

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

Этот подход проще реализовать и позволяет синхронизировать каталог с окном наименьшего количества расхождений.

Когда использовать периодические обновления

Периодические обновления запускаются асинхронно с версией продукта на вашем сервере и являются хорошим вариантом, когда:

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

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

Создайте свой каталог продукции

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

Создавайте одноразовые продукты

Для первоначального однократного создания большого каталога продуктов мы рекомендуем использовать метод inappproducts.batchUpdate с allowMissing , установленным в значение true , а поле latencyTolerance , установленным в PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT . Это позволит свести к минимуму время, необходимое для создания каталога в пределах квоты.

Для небольших каталогов вы можете использовать метод inapp_products.insert . Альтернативно вы можете использовать метод inappproducts.update с allowMissing , как описано в разделе «Обновления продукта». Преимущество этого подхода состоит в том, что вам не нужно сохранять состояние вашего сценария, и его можно перезапустить с нуля, если что-то пойдет не так.

Создавайте продукты по подписке

Для первоначального создания большого каталога подписки мы рекомендуем использовать метод monetization.subscriptions.batchUpdate с allowMissing , установленным в значение true , а поле latencyTolerance , установленным в PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT . Это позволит свести к минимуму время, необходимое для создания каталога в пределах квоты.

Для небольших каталогов подписок Play Developer API предоставляет метод monetization.subscriptions.create . Альтернативно вы можете создавать подписки, используя метод monetization.subscriptions.update с allowMissing , как описано в разделе «Обновления продукта».

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

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

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

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

Вам доступны три метода, которые помогут обновить существующие одноразовые продукты.

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

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

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

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

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

Устаревание продукта

API разработчика Google Play предлагает несколько методов, которые помогут разработчикам прекратить поддержку их продуктов: inappproducts.delete и inappproducts.batchDelete для одноразовых продуктов и monetization.subscriptions.delete для подписок. Отмена поддержки продукта может потребоваться в различных сценариях, например:

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

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

Устаревшие одноразовые продукты

Чтобы удалить одноразовые продукты с помощью API разработчика Google Play, вам необходимо использовать метод inappproducts.delete или inappproducts.batchDelete .

Устаревшие продукты по подписке

Удалить подписки можно с помощью monetization.subscriptions.delete . Подписку нельзя удалить после активации хотя бы одного базового плана.