Ce guide explique comment utiliser l'API Google Play Developer pour créer et 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 proposer à l'achat à vos utilisateurs. Pour ce faire, 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 à vous assurer que votre catalogue est toujours à jour et à l'adapter à des catalogues volumineux pour lesquels une coordination manuelle n'est pas possible. Dans ce guide, vous allez découvrir comment utiliser l'API Play Developer pour créer et gérer un catalogue de produits pour votre application Play. Consultez notre guide Préparation pour savoir comment configurer l'API Google Play Developer pour l'intégration de votre backend.
API Catalog Management
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 Présentation des types de produits intégrés et points d'attention concernant le catalogue. Google propose deux principaux ensembles d'API pour la gestion des catalogues sur Play, correspondant aux deux principales catégories de produits :
- Produits ponctuels
- Produits sur abonnement
Produits ponctuels
Les produits ponctuels (auparavant appelés "produits intégrés") utilisent le modèle d'objet "produit ponctuel", qui vous permet de configurer plusieurs options d'achat et offres pour vos produits ponctuels. Le modèle d'objet de produit ponctuel vous offre une plus grande flexibilité pour vendre vos produits et simplifie leur gestion. Vos produits intégrés existants seront migrés vers le modèle d'objet "produit ponctuel". Pour en savoir plus, consultez Migration des produits intégrés.
Les points de terminaison monetization.onetimeproducts et inappproducts vous permettent de gérer les produits ponctuels depuis votre backend. Cela inclut la création, la mise à jour et la suppression de produits, ainsi que la gestion des prix et de la disponibilité. Selon la façon dont vous gérez les achats de produits ponctuels, vous modéliserez des produits consommables (pouvant être achetés autant de fois que souhaité) ou des droits permanents (ne pouvant pas être achetés deux fois par le même utilisateur). 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 depuis votre backend de développeur. Vous pouvez par exemple créer, modifier 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 forfaits de base et les offres des abonnements.
Méthodes par lot
Les points de terminaison onetimeproducts, inappproducts et monetization.subscriptions fournissent un certain nombre de méthodes par lot qui permettent de récupérer ou de gérer jusqu'à 100 entités sous la même application en même temps.
Les méthodes par lot, lorsqu'elles sont utilisées avec la tolérance de latence activée, permettent d'obtenir un débit plus élevé et sont particulièrement utiles pour les développeurs de catalogues volumineux pour la création initiale ou le rapprochement de catalogues.
Latence de propagation des mises à jour par rapport au débit
Une fois qu'une demande de création ou de modification de produit est terminée, il est possible que les modifications ne soient pas immédiatement visibles par les utilisateurs finaux sur leurs appareils en raison de retards de traitement du réseau ou du backend. Par défaut, toutes les demandes de modification de produit sont sensibles à la latence. Cela signifie qu'elles sont optimisées pour une propagation rapide via les systèmes de backend, et qu'elles sont généralement répercutées sur les appareils des utilisateurs finaux en quelques minutes.
Toutefois, le nombre de demandes de modification de ce type est limité par heure.
Si 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 par lot avec le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Cela augmentera considérablement le débit de mise à jour. La propagation des mises à jour tolérant la latence sur les appareils des utilisateurs finaux peut prendre jusqu'à 24 heures.
Configuration de quota
Vous devez connaître plusieurs limites de quota lorsque vous utilisez l'API Play Developer pour gérer votre catalogue de produits :
- Les API Google Play Developer sont organisées en catégories appelées "buckets", chacune ayant sa propre limite de quota par minute. Pour en savoir plus, consultez la page consacrée aux quotas.
- Les points de terminaison de modification de produit appliquent également une limite de 7 200 requêtes par heure. Cette limite s'applique à la fois aux produits ponctuels et aux abonnements, ainsi qu'à 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 sont comptabilisés comme une seule requête pour ce quota, quel que soit le nombre de requêtes individuelles incluses ou leur sensibilité à la latence.
- 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 ce quota. Ce quota n'a d'implications pratiques que pour les utilisateurs de l'API par lot qui effectuent des mises à jour sensibles à la latence, car dans les autres cas, le quota 2 sera épuisé avant ou en même temps que ce quota.
Voici plusieurs exemples illustrant l'utilisation des quotas pour différentes requêtes :
- Une seule requête
getpour récupérer un élément consomme 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
getpar lot permettant de récupérer jusqu'à 100 éléments consommera également un jeton du quota 1 et aucun jeton des quotas 2 et 3. - Une seule requête
modificationpour un élément consomme un jeton du quota 1 et un jeton du quota 2. Si la requête est sensible à la latence, elle consommera é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 qui n'utilisent que des méthodes de modification unique. - Une requête par lot
modificationpour 100 éléments tolérants à la latence consommera un jeton du quota 1 et un jeton du quota 2. Cette configuration de quota devrait vous laisser une marge suffisante pour maintenir votre catalogue à jour. Toutefois, si votre algorithme ne tient pas compte de ce quota et dépasse ce taux, vous risquez de recevoir une erreur par appel supplémentaire. - Une requête par lot
modificationpour 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 vous garantit une expérience de gestion de catalogue fluide et efficace.
Surveiller votre utilisation
Vous devez être conscient des processus d'utilisation intensive. Par exemple, au début de votre intégration, vos points de terminaison de gestion du catalogue sont plus susceptibles de consommer davantage de quota pour créer votre catalogue initial complet. Cela pourrait potentiellement affecter l'utilisation en production d'autres points de terminaison, comme l'API d'état d'achat, si vous êtes proche de la limite d'utilisation globale. Vous devez surveiller votre consommation de quota pour vous assurer de ne pas dépasser 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 de surveillance des API interne ou tiers de votre choix.
Optimiser l'utilisation des quotas d'API
Nous vous recommandons vivement d'optimiser la consommation des quotas pour réduire le risque d'erreurs d'API. Pour une implémentation efficace, nous vous recommandons de suivre les conseils suivants :
- Choisissez la bonne stratégie de gestion de catalogue. Une fois que vous avez compris le quota d'API, vous devez choisir la stratégie appropriée pour votre application afin d'atteindre efficacement vos objectifs de gestion de catalogue.
- N'effectuez que le nombre minimal d'appels nécessaires pour refléter vos modifications.
- N'envoyez pas d'appels de modification redondants ou inutiles aux API. Pour cela, vous devrez peut-être conserver un journal des modifications dans votre catalogue backend.
- Ne dépassez pas la limite horaire de 7 200 requêtes pour la modification de produits. Vous pouvez créer des processus de synchronisation qui nécessitent d'apporter un grand nombre de modifications aux produits en peu de temps (par exemple, lors de la création initiale d'un catalogue). Si vous pensez que ces processus dépasseront la limite horaire, mettez en place des temps d'attente 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 de manière proactive à l'évolutivité. À mesure que votre application se développe, vous devrez peut-être augmenter votre utilisation de l'API et des différents points de terminaison. Consultez la documentation sur les quotas de l'API Google Play Developer pour savoir comment augmenter votre quota lorsque vous approchez de l'utilisation maximale.
- Planifiez stratégiquement les processus lourds. Essayez de planifier vos processus de catalogue lourds en dehors des pics d'utilisation critiques. Par exemple, vous pouvez éviter d'exécuter une synchronisation complète du catalogue pendant les pics de ventes de la semaine.
Ajouter une logique de gestion des erreurs de quota
Quelle que soit l'efficacité de votre logique de gestion de catalogue, vous devez la rendre résiliente aux limites de quota inattendues, car le quota quotidien est partagé par les points de terminaison utilisés dans les modules indépendants de votre intégration. Assurez-vous d'inclure les erreurs de limitation de quota dans votre gestion des exceptions et d'implémenter les attentes appropriées. Chaque appel effectué vers les API Google Play Developer génère une réponse. En cas d'échec de l'appel, vous recevrez une réponse d'échec incluant un code d'état de réponse HTTP et un objet errors, qui fournit 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 du catalogue
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. En vous assurant que votre catalogue Google Play est toujours à jour avec les dernières informations du catalogue de votre backend, vous pouvez améliorer l'expérience utilisateur. 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 des offres.
- 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 aurez les informations détaillées sur le produit à portée de main dans votre backend lors du traitement des nouveaux achats, sans avoir à augmenter la latence ni le risque d'échec en effectuant des appels supplémentaires à l'API Google Play Developer pendant les flux critiques des utilisateurs.
Vous devez tenir compte de certaines limites et considérations lorsque vous créez votre catalogue de produits sur Google Play. Une fois que vous avez compris ces limites et que vous savez comment vous souhaitez structurer votre catalogue, vous devez décider de 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 au fur et à mesure des modifications. Parfois, vous devrez peut-être adopter une approche de mises à jour périodiques, dans laquelle vous envoyez une série de modifications dans le même processus. Chaque approche nécessite des choix de conception différents. Chaque stratégie de synchronisation est plus adaptée à certains cas d'utilisation qu'à d'autres, et vous pouvez avoir un ensemble de besoins qui nécessite les deux, selon la situation.
Il peut arriver que vous souhaitiez mettre à jour un produit dès que vous avez connaissance d'un changement, par exemple pour traiter une mise à jour urgente (par exemple, un prix incorrect doit être corrigé dès que possible). Dans d'autres cas, vous pouvez utiliser une synchronisation périodique en arrière-plan pour vous assurer que votre backend et vos catalogues Play sont toujours cohérents. Découvrez quelques cas d'utilisation courants dans lesquels vous pouvez implémenter ces différentes stratégies de gestion de catalogue.
Quand envoyer des mises à jour lorsque votre catalogue en magasin change
Idéalement, les mises à jour doivent être effectuées 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 une bonne option 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 vente.
Cette approche est plus simple à mettre en œuvre et vous permet de maintenir votre catalogue synchronisé avec la fenêtre d'écart la plus faible.
Quand utiliser les mises à jour périodiques
Les mises à jour périodiques sont exécutées de manière asynchrone par rapport à 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 des mises à jour groupées ou des processus de conciliation.
- Vous disposez déjà d'un système de gestion de contenu ou de catalogue pour gérer vos produits numériques, et ce système met constamment à jour votre catalogue.
Pour les catalogues volumineux, envisagez d'utiliser des méthodes par lot avec des mises à jour tolérantes à la latence afin d'obtenir un débit maximal.
Créer votre catalogue de produits
Si vous avez un catalogue volumineux à importer sur Google Play, vous pouvez automatiser le chargement initial. Ce type de processus lourd fonctionne mieux si une stratégie périodique combinée à des méthodes de traitement par lot tolérantes à la latence est suivie.
Créer des produits ponctuels
Pour la création initiale d'un catalogue de produits ponctuels, nous vous recommandons d'utiliser la méthode monetization.onetimeproducts.batchUpdate ou inapp_products.insert avec le champ allowMissing défini sur true et le champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT. Cela réduit le temps nécessaire pour créer le catalogue dans les limites de quota.
Créer des produits sur abonnement
Pour créer un catalogue volumineux d'abonnements initiaux, 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 de quota.
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.patch 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 ainsi que 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 pour activer un forfait de base afin de 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 sur les produits
Les méthodes suivantes vous permettent de modifier efficacement vos produits existants, afin de vous assurer que vos offres sont conformes à vos derniers ajustements.
Mettre à jour les produits ponctuels
Les méthodes suivantes sont disponibles pour vous aider à mettre à jour des produits ponctuels existants.
- monetization.onetimeproducts.batchUpdate
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 de correctif 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 de 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ètreallowMissingest défini surtrueet que l'identifiant produit fourni n'existe pas déjà, le point de terminaison insère le produit au lieu d'échouer.inappproducts.batchUpdate: il s'agit d'une version par lot du point de terminaison de mise à jour, qui vous permet de modifier plusieurs produits avec une seule requête. Utilisez-le avec le champlatencyTolerancedéfini surPRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANTpour 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 l'abonnement appartient.productId: ID produit unique de l'abonnement.
regionsVersion: version de la configuration de la région.
Sauf si vous créez un abonnement à l'aide du paramètre allowMissing, vous devez fournir le paramètre updateMask. 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 pour le paramètre updateMask.
Vous pouvez utiliser monetization.subscriptions.batchUpdate pour mettre à jour plusieurs abonnements en même temps.
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 des forfaits de base, ou pour migrer des abonnés vers les dernières versions de prix des forfaits de base, utilisez le point de terminaison monetization.subscriptions.basePlans.
Vous pouvez également mettre à jour les offres de vos forfaits de base à l'aide de la méthode monetization.subscriptions.basePlans.offers.patch.
Rapprochement de catalogues
Que vous choisissiez de mettre à jour votre catalogue Google Play chaque fois que le catalogue de votre backend change ou de manière périodique, si vous disposez d'un système de gestion de catalogue ou d'une base de données en dehors du catalogue Google Play, il peut arriver qu'il ne soit plus synchronisé avec le catalogue de la configuration de vos applications sur Play. Cela peut être dû à des modifications manuelles d'urgence du catalogue dans la console, à une indisponibilité de votre système de gestion de catalogue ou à la perte de vos dernières données.
Vous pouvez créer un processus de rapprochement de catalogue pour éviter une période d'écart prolongée.
Remarques concernant le système de diff
Nous vous recommandons de créer un système de comparaison 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 comparaison pour vous aider à synchroniser vos catalogues :
- Comprendre les modèles de données : la première étape consiste à comprendre les modèles de données du CMS du développeur et de l'API Google Play Developer. Cela implique de connaître les 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éfinir les règles de comparaison : une fois que vous avez compris les modèles de données, vous devez définir les règles de comparaison. Ces règles détermineront la manière dont les données des deux systèmes seront comparées. Par exemple, vous pouvez faire correspondre les identifiants produit et comparer les attributs clés de l'abonnement, ainsi que ses forfaits de base et ses offres associés.
- Implémenter un algorithme de comparaison : une fois que vous avez défini les règles de comparaison, vous devez implémenter l'algorithme de comparaison. Cet algorithme prendra les données des deux systèmes et les comparera selon les règles que vous avez définies. Pour obtenir les données du catalogue à partir de Google Play, vous pouvez utiliser les méthodes
monetization.onetimeproducts.list,monetization.onetimeproducts.batchGet,inappproducts.list,inappproducts.batchGet,monetization.subscriptions.listetmonetization.subscriptions.batchGet. - Générer des rapports de différence : l'algorithme de différence génère un rapport de différence. Ce rapport met en évidence 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 de mettre à jour les données dans votre CMS ou de mettre à jour les données côté Google Play à l'aide des points de terminaison de gestion du catalogue de l'API Developer, selon la façon dont vous mettez habituellement à jour votre catalogue. Pour rapprocher les produits non synchronisés, utilisez les points de terminaison de mise à jour comme décrit dans la section "Mises à jour de produits".
Abandon de produit
L'API Google Play Developer fournit les méthodes suivantes pour vous aider à abandonner vos produits :
Pour les produits ponctuels :
monetization.onetimeproducts.deletemonetization.onetimeproducts.batchDeleteinappproducts.deleteinappproducts.batchDelete
Pour les produits sur abonnement :
monetization.subscriptions.deletepour les abonnements. Un abonnement ne peut pas être supprimé une fois qu'au moins un forfait de base a été activé.
L'abandon d'un produit peut être nécessaire dans différents scénarios, par exemple :
- Création 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 de catalogue.