Gérer votre catalogue de produits

Ce guide explique comment utiliser l'API Google Play Developer afin de créer et de gérer un catalogue de produits pour votre application Play.

Pour vendre des produits dans votre application via le système de facturation de Google Play, vous devez configurer un catalogue contenant tous les produits que vous souhaitez mettre à la disposition des utilisateurs. Pour cela, vous pouvez utiliser la Play Console ou automatiser la gestion du catalogue à l'aide de l'API Google Play Developer. L'automatisation peut vous aider à garantir que votre catalogue est toujours à jour et à l'adapter aux catalogues volumineux où la coordination manuelle n'est pas pratique. Dans ce guide, vous allez apprendre à utiliser l'API Play Developer afin de créer et de gérer un catalogue de produits pour votre application Play. Consultez notre guide de préparation pour savoir comment configurer l'API Google Play Developer pour votre intégration backend.

API de gestion du catalogue

Pour en savoir plus sur les différents types de produits que vous pouvez vendre avec le système de facturation de Google Play, consultez la page Comprendre les types de produits intégrés et les considérations liées au catalogue. Google propose deux ensembles principaux d'API pour la gestion des catalogues sur Play, correspondant aux deux principales catégories de produits:

• Produits ponctuels
• Produits sur abonnement

Produits ponctuels

Le point de terminaison inappproducts vous permet de gérer des produits ponctuels à partir du backend. Cela inclut la création, la mise à jour et la suppression de produits, ainsi que la gestion des prix et des disponibilités. Selon la façon dont vous gérez les achats de produits uniques, vous allez modéliser les produits consommables (qui peuvent être achetés autant de fois que vous le souhaitez) ou les droits d'accès permanents (le même utilisateur ne peut pas effectuer deux fois cette opération). Vous pouvez décider quels produits ponctuels doivent être consommables ou non.

Produits sur abonnement

Le point de terminaison monetization.subscriptions vous aide à gérer les produits sur abonnement à partir de votre backend de développeur. Vous pouvez par exemple créer, mettre à jour et supprimer des abonnements, ou contrôler leur disponibilité et leur tarification selon la région. En plus du point de terminaison monetization.subscriptions, nous fournissons également monetization.subscriptions.basePlans et monetization.subscriptions.basePlans.offers pour gérer respectivement les offres et les forfaits de base des abonnements.

Méthodes par lot

Les points de terminaison inappproducts et monetization.subscriptions fournissent un certain nombre de méthodes de traitement par lot qui permettent de récupérer ou de gérer simultanément jusqu'à 100 entités sous la même application.

Les méthodes par lot, lorsqu'elles sont utilisées avec une tolérance à la latence activée, acceptent un débit plus élevé et sont particulièrement utiles pour les développeurs de catalogues volumineux pour la création initiale de catalogues ou le rapprochement de catalogues.

Mettre à jour la latence de propagation par rapport au débit

Une fois la requête de création ou de modification de produit traitée, il est possible que les utilisateurs finaux ne voient pas immédiatement les modifications sur leurs appareils en raison des retards de traitement sur le réseau ou le backend. Par défaut, toutes les demandes de modification de produit sont sensibles à la latence. Cela signifie qu'ils sont optimisés pour une propagation rapide via les systèmes backend, généralement en quelques minutes sur les appareils des utilisateurs finaux. Toutefois, le nombre de requêtes de modification de ce type est limité par heure. Dans les cas où vous devez créer ou mettre à jour de nombreux produits (par exemple, lors de la création initiale d'un catalogue volumineux), vous pouvez utiliser des méthodes de traitement par lot avec le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Cela augmentera considérablement le débit des mises à jour. La propagation des mises à jour tolérantes à la latence peut prendre jusqu'à 24 heures.

Configuration des quotas

Il existe plusieurs limites de quota que vous devez prendre en compte lorsque vous utilisez l'API Play Developer pour gérer votre catalogue de produits:

1. Les API Google Play Developer ont une limite par défaut de 200 000 requêtes par jour. Cette limite de quota s'applique à l'agrégation de l'utilisation sur tous les points de terminaison, y compris les API de gestion des catalogues.
2. Les points de terminaison de modification de produits appliquent également une limite de 7 200 requêtes par heure. Il s'agit d'une limite unique pour les produits ponctuels et les abonnements, et pour toutes les demandes de modification, y compris la création, la mise à jour, l'activation et la suppression. Les appels de méthode de modification par lot comptent comme une requête pour ce quota, quelle que soit le nombre de requêtes individuelles incluses ou leur sensibilité à la latence.
3. Les modifications sensibles à la latence sont également limitées à 7 200 modifications par heure. Pour les méthodes par lot, chaque requête de modification imbriquée est comptabilisée séparément pour les besoins de ce quota. Ce quota n'a des conséquences pratiques que pour les utilisateurs d'API par lot qui effectuent des mises à jour sensibles à la latence, car dans d'autres cas, le quota 2 sera épuisé avant ou en même temps que ce quota.

Voici plusieurs exemples illustrant l'utilisation du quota par différentes requêtes:

• Une seule requête get d'extraction d'un élément consommera un jeton du quota 1 et aucun jeton des quotas 2 et 3 (car ils ne concernent que les points de terminaison de modification).
• Une requête get par lot pour récupérer jusqu'à 100 éléments consomme également un jeton du quota 1, mais aucun jeton des quotas 2 et 3.
• Une seule requête modification pour un élément consommera un jeton du quota 1 et un jeton du quota 2. Si la requête est sensible à la latence, elle consomme également un jeton du quota 3. Étant donné que le quota C a la même limite que le quota 2, il n'a aucune incidence pratique pour les utilisateurs n'utilisant que des méthodes de modification unique.
• Une requête modification par lot pour 100 éléments tolérants à la latence consommera un jeton du quota 1 et un jeton du quota 2. Cette configuration de quota doit permettre une marge suffisante pour maintenir votre catalogue à jour, mais si votre algorithme ne tient pas compte de ce quota et dépasse ce taux, vous risquez de recevoir une erreur pour chaque appel supplémentaire.
• Une requête modification par lot pour 100 éléments sensibles à la latence consomme un jeton du quota 1, un jeton du quota 2 et 100 jetons du quota 3.

Recommandations d'utilisation de l'API Catalog Management

En respectant ces consignes, vous optimisez vos interactions avec l'API, ce qui garantit une expérience de gestion des catalogues fluide et efficace.

Surveiller votre utilisation

Vous devez être conscient des processus d'utilisation intensive. Par exemple, au début de l'intégration, vos points de terminaison de gestion des catalogues sont plus susceptibles de consommer plus de quota pour créer votre catalogue initial complet. Cela peut affecter l'utilisation en production d'autres points de terminaison, tels que l'API purchase status, si vous approchez de la limite d'utilisation globale. Vous devez surveiller votre consommation de quotas pour vous assurer que vous ne dépassez pas les quotas d'API. Il existe plusieurs façons de surveiller l'utilisation. Par exemple, vous pouvez utiliser le tableau de bord des quotas des API Google Cloud, ou tout autre outil interne ou tiers de surveillance des API de votre choix.

Optimiser l'utilisation des quotas d'API

L'optimisation de la consommation du taux est vivement recommandée pour minimiser la probabilité d'erreurs d'API. Pour une mise en œuvre efficace, nous vous recommandons de suivre ces recommandations:

• Choisissez la bonne stratégie de gestion des catalogues. Une fois que vous avez compris quel est le quota d'API, vous devez choisir la stratégie adaptée à votre application afin d'atteindre efficacement vos objectifs de gestion de catalogue.
• Ne passez que le nombre d'appels minimal dont vous avez besoin pour refléter vos modifications.
• N'envoyez pas d'appels de modification redondants ou inutiles aux API. Vous devrez peut-être conserver un journal des modifications dans votre catalogue backend.
• Respectez la limite horaire de modification de produit de 7 200 requêtes. Vous souhaiterez peut-être créer des processus de synchronisation qui nécessitent d'apporter un grand nombre de modifications de produits sur une courte période (par exemple, la création initiale d'un catalogue). Si vous pensez que ces processus dépassent la limite horaire, implémentez des temps d'attente autant que nécessaire pour ralentir l'utilisation à un niveau sûr. Envisagez d'utiliser des méthodes par lot avec des mises à jour tolérantes à la latence pour obtenir un débit plus élevé.
• Préparez-vous à évoluer de manière proactive. À mesure que votre application se développe, vous devrez peut-être augmenter votre utilisation de l'API et des différents points de terminaison. Lisez la documentation sur les quotas de l'API Google Play Developer pour savoir comment augmenter votre quota lorsque vous vous approchez de son utilisation maximale.
• Planifier de manière stratégique des processus lourds. Essayez de planifier vos processus de catalogue lourds en fonction des pics d'utilisation critiques. Par exemple, vous pouvez éviter d'exécuter une synchronisation complète du catalogue pendant vos pics de vente de la semaine.

Ajouter une logique de gestion des erreurs de quota

Quelle que soit l'efficacité avec laquelle vous créez votre logique de gestion de catalogue, vous devez la rendre résiliente face aux limites de quota inattendues, étant donné que le quota quotidien est partagé par les points de terminaison utilisés dans des modules indépendants de votre intégration. Assurez-vous d'inclure les erreurs de limitation de quota dans votre traitement des erreurs et mettez en œuvre les temps d'attente appropriés. Chaque appel effectué vers les API Google Play Developer génère une réponse. En cas d'échec d'un appel, vous recevez une réponse d'échec comprenant un code d'état de réponse HTTP et un objet errors, fournissant des détails supplémentaires sur le domaine d'erreur et un message de débogage. Par exemple, si vous dépassez votre limite quotidienne, vous pouvez rencontrer une erreur semblable à celle-ci:

{
  "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"
  } ],
}

Implémentation de la gestion des catalogues

Les développeurs utilisent les points de terminaison de publication de produits de l'API Google Play Developer pour synchroniser leur catalogue entre leur backend et Google Play. Vous assurer que votre catalogue Google Play est toujours à jour avec les dernières informations du catalogue de votre backend présente des avantages pour créer une meilleure expérience utilisateur. Par exemple :

• Vous pourrez consulter la liste complète des offres disponibles, et gérer les tags des offres et des forfaits de base pour influencer votre propre éligibilité et la logique d'affichage de l'offre.
• Vous pouvez vérifier les différents prix et informations détaillées sur les produits que les utilisateurs voient sur les différentes plates-formes, et vous assurer qu'ils sont cohérents.
• Vous disposerez ainsi des informations détaillées sur le produit dans votre backend lorsque vous traiterez les nouveaux achats. Vous éviterez d'augmenter la latence et le risque d'échec en effectuant des appels supplémentaires à l'API Google Play Developer pendant les flux critiques de l'utilisateur.

Lorsque vous créez votre catalogue de produits sur Google Play, vous devez tenir compte de certaines limites et considérations. Une fois que vous avez compris ces limites et que vous savez comment vous souhaitez structurer votre catalogue, il est temps de choisir votre stratégie de synchronisation.

Stratégies de synchronisation du catalogue

Les points de terminaison de publication de l'API Google Play Developer vous permettent de mettre à jour votre catalogue à mesure que des modifications se produisent. Vous devrez peut-être parfois adopter une approche périodique des mises à jour, consistant à envoyer une batterie de modifications au cours du même processus. Chaque approche nécessite des choix de conception différents. Chaque stratégie de synchronisation convient mieux à certains cas d'utilisation que d'autres. Selon la situation, vous pouvez avoir un ensemble de besoins répondant aux deux. Vous pouvez parfois vouloir mettre à jour un produit au moment où vous avez connaissance d'une nouvelle modification, par exemple pour traiter une mise à jour urgente du produit (par exemple, un prix incorrect doit être corrigé le plus rapidement possible). Vous pouvez également utiliser une synchronisation périodique en arrière-plan pour vous assurer que vos catalogues backend et Play sont toujours cohérents. Consultez quelques cas d'utilisation courants dans lesquels vous pouvez mettre en œuvre ces différentes stratégies de gestion des catalogues.

Quand envoyer des mises à jour lorsque votre catalogue en magasin évolue ?

Idéalement, les mises à jour doivent avoir lieu dès qu'une modification est apportée au catalogue de produits de votre backend afin de minimiser les écarts.

Ce type de mise à jour est particulièrement utile dans les cas suivants:

• Vous devez vous assurer que vos produits sont toujours à jour.
• Vous devez apporter quelques modifications à vos produits chaque jour.
• Vous devez mettre à jour des produits qui sont déjà en production et en cours de vente.

Cette approche est plus simple à mettre en œuvre et vous permet de synchroniser votre catalogue avec un intervalle d'écart minimal.

Quand utiliser les mises à jour périodiques ?

Les mises à jour périodiques sont exécutées de manière asynchrone vers l'édition du produit sur votre backend. Elles constituent une bonne option dans les cas suivants:

• Vous n'avez pas besoin de vous assurer que vos produits sont mis à jour rapidement.
• Vous devez planifier les mises à jour groupées ou les processus de rapprochement.
• Vous disposez déjà d'un système de gestion de contenu ou de catalogue pour gérer vos produits numériques,

Dans le cas de catalogues volumineux, envisagez d'utiliser des méthodes par lot avec des mises à jour tolérantes à la latence pour obtenir un débit maximal.

Créer votre catalogue de produits

Si vous avez un vaste catalogue à importer sur Google Play, vous pouvez automatiser le chargement initial. Ce type de processus lourd fonctionne mieux si vous suivez une stratégie périodique associée à des méthodes par lot tolérantes à la latence.

Créer des produits ponctuels

Pour la création unique d'un grand catalogue de produits volumineux, nous vous recommandons d'utiliser la méthode inappproducts.batchUpdate avec le champ allowMissing défini sur true et le champ latencyTolerance sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Cela réduira le temps nécessaire pour créer le catalogue dans les limites des quotas.

Pour les catalogues de petite taille, vous pouvez utiliser la méthode inapp_products.insert. Vous pouvez également utiliser la méthode inappproducts.update avec le paramètre allowMissing, comme décrit dans la section "Mises à jour de produits". Cette approche présente l'avantage de ne plus nécessiter que votre script soit avec état et puisse être redémarré à partir de zéro en cas de problème.

Créer des produits sur abonnement

Pour créer un catalogue d'abonnements volumineux initial, nous vous recommandons d'utiliser la méthode monetization.subscriptions.batchUpdate avec le champ allowMissing défini sur true et le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Cela réduira le temps nécessaire pour créer le catalogue dans les limites des quotas.

Pour les catalogues d'abonnements plus petits, l'API Play Developer fournit la méthode monetization.subscriptions.create. Vous pouvez également créer des abonnements à l'aide de la méthode monetization.subscriptions.update avec le paramètre allowMissing, comme décrit dans la section "Mises à jour de produits".

Toutes les méthodes précédentes créent des abonnements avec leurs forfaits de base (fournis dans l'objet Subscription). Ces forfaits de base sont initialement inactifs. Pour gérer l'état des forfaits de base, vous pouvez utiliser le point de terminaison monetization.subscriptions.basePlans, y compris en activant un forfait de base pour le rendre disponible à l'achat. De plus, le point de terminaison monetization.subscriptions.basePlans.offers vous permet de créer et de gérer des offres.

Actualités du produit

Les méthodes suivantes vous permettent de modifier efficacement vos produits existants, en vous assurant que vos offres correspondent à vos derniers ajustements.

Mettre à jour les produits ponctuels

Trois méthodes s'offrent à vous pour mettre à jour les produits ponctuels existants.

• inappproducts.patch : le point de terminaison de correctif permet de mettre à jour partiellement une ressource. Cela signifie que vous pouvez mettre à jour des champs spécifiques que vous spécifiez dans le corps de la requête. Le point de terminaison "patch" est généralement utilisé lorsque vous n'avez besoin de mettre à jour que quelques champs d'une ressource.
• inappproducts.update : le point de terminaison de mise à jour permet de mettre à jour une ressource dans son intégralité. Cela signifie que vous devrez envoyer l'intégralité de l'objet ressource dans le corps de la requête. Le point de terminaison de mise à jour est généralement utilisé lorsque vous devez mettre à jour tous les champs d'une ressource. Lorsque le paramètre allowMissing est défini sur true et que l'ID produit fourni n'existe pas déjà, le point de terminaison insère le produit au lieu d'échouer.
• inappproducts.batchUpdate : version par lot du point de terminaison de mise à jour, qui vous permet de modifier plusieurs produits à l'aide d'une seule requête. Utilisez-le avec le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT pour obtenir un débit plus élevé.

Mettre à jour les produits sur abonnement

Pour mettre à jour des abonnements existants, vous pouvez utiliser la méthode monetization.subscriptions.patch. Cette méthode utilise les paramètres obligatoires suivants:

• packageName: nom du package de l'application à laquelle appartient l'abonnement.
• productId: ID produit unique de l'abonnement.
• regionsVersion: version de la configuration de la région.

Vous devez fournir le paramètre updateMask, sauf si vous créez un abonnement à l'aide du paramètre allowMissing. Ce paramètre est une liste de champs à mettre à jour, séparés par une virgule.

Par exemple, si vous souhaitez uniquement mettre à jour la fiche d'un produit sur abonnement, vous devez spécifier le champ listings dans le paramètre updateMask.

monetization.subscriptions.batchUpdate vous permet de mettre à jour plusieurs abonnements à la fois. Utilisez-le avec le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT pour obtenir un débit plus élevé.

Pour activer, désactiver ou supprimer les forfaits de base, ou pour faire migrer les abonnés vers les dernières versions du forfait de base, utilisez le point de terminaison monetization.subscriptions.basePlans.

Vous pouvez également mettre à jour les offres de vos forfaits de base avec la méthode monetization.subscriptions.basePlans.offers.patch.

Rapprochement du catalogue

Que vous choisissiez de mettre à jour votre catalogue Google Play chaque fois que le catalogue de votre backend change ou de façon périodique, si vous disposez d'un système de gestion de catalogues ou d'une base de données ne faisant pas partie du catalogue Google Play, il peut arriver que le catalogue ne soit pas synchronisé avec le catalogue dans la configuration de vos applications sur Play. Cela peut être dû à des modifications manuelles urgentes du catalogue dans la console, à une indisponibilité de votre système de gestion de catalogues ou à la perte de vos dernières données.

Vous pouvez créer un processus de rapprochement du catalogue pour éviter un écart prolongé.

Prise en compte des différences du système

Nous vous recommandons de créer un système de différences pour détecter les incohérences et rapprocher les deux systèmes. Voici quelques éléments à prendre en compte lors de la création d'un système de différences pour synchroniser vos catalogues:

• Comprendre les modèles de données:la première étape consiste à comprendre les modèles de données du CMS pour développeurs et de l'API Google Play Developer. Cela inclut la connaissance des différents types de données stockés dans chaque système et la manière dont les différents éléments de données sont mappés les uns aux autres.
• Définissez les règles de différences:une fois que vous avez compris les modèles de données, vous devez définir les règles de différences. Ces règles détermineront comment les données des deux systèmes sont comparées. Par exemple, vous pouvez mettre en correspondance les ID produit et comparer les attributs clés de l'abonnement ainsi que des offres et forfaits de base associés.
• Implémentez un algorithme de différences:une fois que vous avez défini les règles de différences, vous devez implémenter l'algorithme de différences. Cet algorithme extrait les données des deux systèmes et les compare en fonction des règles que vous avez définies. Pour obtenir les données du catalogue à partir de Google Play, vous pouvez utiliser les méthodes inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list et monetization.subscriptions.batchGet.
• Générer des rapports de différences:l'algorithme génère un rapport de différences. Ce rapport indiquera les différences entre les deux systèmes.
• Rapprocher les différences:une fois que vous avez généré le rapport de différences, vous devez résoudre les différences. Cela peut impliquer la mise à jour des données dans votre CMS ou la mise à jour des données côté Google Play à l'aide des points de terminaison de gestion du catalogue de l'API Developer, selon la manière dont vous mettez normalement à jour votre catalogue. Pour rapprocher des produits non synchronisés, utilisez les points de terminaison de mise à jour comme décrit dans la section "Mises à jour de produits".

Abandon de produits

L'API Google Play Developer propose plusieurs méthodes pour aider les développeurs à abandonner leurs produits : inappproducts.delete et inappproducts.batchDelete pour les produits ponctuels et monetization.subscriptions.delete pour les abonnements. L'abandon d'un produit peut être nécessaire dans divers scénarios, par exemple:

• Il a été créé par erreur.
• Arrêt d'une fonctionnalité ou d'un service

Nous vous recommandons d'intégrer l'abandon de produits dans votre stratégie de gestion des catalogues.

Abandonner les produits ponctuels

Pour supprimer des produits ponctuels avec l'API Google Play Developer, vous devez utiliser la méthode inappproducts.delete ou inappproducts.batchDelete.

Abandon des produits sur abonnement

Vous pouvez supprimer des abonnements à l'aide de la méthode monetization.subscriptions.delete. Un abonnement ne peut pas être supprimé une fois qu'au moins un forfait de base a été activé.