Gérer votre catalogue de produits

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 avec tous les produits que vous souhaitez mettre à la disposition de vos utilisateurs. Vous pouvez le faire depuis 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 aux grands catalogues pour lesquels la coordination manuelle n'est pas pratique. Ce guide vous explique 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 votre intégration de 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 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 du catalogue sur Play, correspondant aux deux principales catégories de produits :

  • Produits ponctuels
  • Produits sur abonnement

Produits ponctuels

Les produits ponctuels (anciennement 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 les produits consommables (qui peuvent être achetés autant de fois que souhaité) ou les droits d'accès permanents (qui ne peuvent pas être achetés deux fois par le même utilisateur). Vous pouvez décider si les produits ponctuels doivent être consommables ou non.

Produits sur abonnement

Le point de terminaison monetization.subscriptions vous aide à gérer les produits d'abonnement depuis le backend de votre 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.

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

Latence de propagation des mises à jour par rapport au débit

Une fois une demande de création ou de modification de produit traité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 produits sont sensibles à la latence. Cela signifie qu'elles sont optimisées pour une propagation rapide dans les systèmes de backend, et qu'elles sont généralement reflété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 grand catalogue), 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 des mises à jour. La propagation des mises à jour tolérant la latence sur les appareils des utilisateurs finaux peut prendre jusqu'à 24 heures.

Configuration des quotas

Lorsque vous utilisez l'API Play Developer pour gérer votre catalogue de produits, vous devez tenir compte de plusieurs limites de quota :

  1. Les API Google Play Developer sont organisées en catégories appelées "buckets", où chaque bucket a sa propre limite de quota par minute. Pour en savoir plus, consultez la page Quotas.
  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 qui 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.
  3. Les modifications sensibles à la latence sont également limitées à 7 200 modifications par heure. Pour les méthodes par lot, chaque demande 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 illustratifs pour comprendre l'utilisation du quota pour différentes requêtes :

  • Une seule requête get pour 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 get par lot permettant de récupérer jusqu'à 100 éléments consommera également un jeton du quota 1, mais aucun jeton des quotas 2 et 3.
  • Une seule requête modification pour un élément consomme un jeton de quota 1 et un jeton de 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 implication pratique pour les utilisateurs qui n'utilisent 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 devrait vous laisser une marge suffisante pour tenir votre catalogue à jour. Toutefois, si votre algorithme ne tient pas compte de ce quota et dépasse ce taux, vous risquez de recevoir un message d'erreur pour chaque appel supplémentaire.
  • Une requête modification par lot pour 100 éléments sensibles à la latence consommera 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 optimiserez vos interactions avec l'API et vous assurerez une gestion fluide et efficace de votre catalogue.

Surveiller votre utilisation

Vous devez connaître les processus d'utilisation intensive. Par exemple, au début de votre intégration, vos points de terminaison de gestion de catalogue sont plus susceptibles de consommer plus 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 des achats, 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 du quota d'API

Nous vous recommandons vivement d'optimiser la consommation de quotas pour minimiser le risque d'erreurs d'API. Pour l'implémenter efficacement, nous vous recommandons de :

  • 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 adaptée à votre application pour 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. Cela peut vous obliger à tenir un journal des modifications dans votre catalogue de 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 vous obligent à 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épasseront la limite horaire, implémentez des pauses si 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 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 volumineux autour des pics d'utilisation critiques. Par exemple, vous pouvez éviter d'exécuter une synchronisation complète du catalogue pendant les périodes de pointe des ventes 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 aux limites de quota inattendues, étant donné que le quota quotidien est partagé par les points de terminaison utilisés dans les modules indépendants de votre intégration. Veillez à inclure les erreurs de limitation du quota dans votre gestion des erreurs et à implémenter les temps d'attente appropriés. Chaque appel effectué aux API Google Play Developer génère une réponse. En cas d'échec d'un appel, vous recevrez une réponse d'échec qui inclut un code d'état de réponse HTTP et un objet errors, fournissant plus de détails 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 veillant à ce que votre catalogue Google Play soit 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 d'offres et de forfaits de base pour influencer votre propre éligibilité et la logique de présentation des offres.
  • Vous pouvez vérifier les différents prix et détails des produits que les utilisateurs voient sur les plates-formes, et vous assurer qu'ils sont cohérents.
  • Vous aurez les détails du produit à portée de main dans votre backend lorsque vous traiterez de nouveaux achats, sans avoir à augmenter la latence ni le risque d'échec en effectuant des appels supplémentaires à l'API Google Play Developer lors des flux critiques pour les 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 structurer votre catalogue, il est temps de choisir votre stratégie de synchronisation.

Stratégies de synchronisation de catalogue

Les points de terminaison de publication de l'API Google Play Developer vous permettent de mettre à jour votre catalogue à mesure que des modifications sont apportées. Parfois, vous devrez peut-être adopter une approche de mise à jour périodique, où 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 convient mieux à certains cas d'utilisation qu'à d'autres. Vous pouvez avoir un ensemble de besoins qui nécessitent les deux, selon la situation. Il peut arriver que vous souhaitiez modifier un produit dès que vous avez connaissance d'un nouveau changement, par exemple pour traiter une mise à jour urgente (c'est-à-dire qu'un prix incorrect doit être corrigé dès que possible). D'autres fois, vous pouvez utiliser une synchronisation périodique en arrière-plan pour vous assurer que vos catalogues backend et 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 local change

Dans l'idéal, les mises à jour doivent avoir lieu dès que le catalogue de produits de votre backend est modifié, afin de minimiser les écarts.

Ce type de mise à jour est une bonne option lorsque :

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

Cette approche est plus simple à implémenter et vous permet de synchroniser votre catalogue avec la fenêtre de différence la plus petite.

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 lorsque :

  • Vous n'avez pas besoin de vous assurer que vos produits sont mis à jour à court terme.
  • Vous devez planifier des mises à jour groupées ou des 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, et celui-ci met constamment à jour votre catalogue.

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 grand catalogue à 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 par lot tolérantes à la latence est suivie.

Créer des produits ponctuels

Pour la création initiale et ponctuelle d'un catalogue de produits, 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 minimisera le temps nécessaire à la création du catalogue dans les limites de quota.

Créer des produits d'abonnement

Pour la création initiale d'un grand catalogue d'abonnements, 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 à la création du 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 "Nouveautés concernant les 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 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 des produits

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

Modifier les produits ponctuels

Les méthodes suivantes sont à votre disposition pour vous aider à mettre à jour les 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è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 : 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 champ latencyTolerance défini sur PRODUCT_UPDATE_LATENCY_TOLERANCE_LATENCY_TOLERANT pour obtenir un débit plus élevé.

Modifier les produits d'abonnement

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

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 ne souhaitez mettre à jour que 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 périodiquement, si vous disposez d'un système de gestion de catalogue ou d'une base de données en dehors du catalogue de Google Play, il peut arriver qu'il se désynchronise du catalogue de la configuration de vos applications sur Play. Cela peut être dû à des modifications manuelles d'urgence apportées au catalogue dans la console, à une panne de votre système de gestion de catalogue ou à une perte de vos dernières données.

Vous pouvez créer un processus de rapprochement du catalogue pour éviter une période de divergence prolongée.

Considérations liées au système de comparaison

Nous vous recommandons de créer un système de comparaison pour détecter les incohérences et concilier les deux systèmes. Voici quelques éléments à prendre en compte lorsque vous créez 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 pour les 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 façon dont les différents éléments de données sont mappés les uns aux autres.
  • Définissez 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 comment les données des deux systèmes sont comparées. Par exemple, vous pouvez faire correspondre des ID de produit et comparer les attributs clés de l'abonnement, ainsi que ses forfaits de base et offres associés.
  • Implémentez 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 sur Google Play, vous pouvez utiliser les méthodes monetization.onetimeproducts.list, monetization.onetimeproducts.batchGet, inappproducts.list, inappproducts.batchGet, monetization.subscriptions.list et monetization.subscriptions.batchGet.
  • Générez des rapports de comparaison : l'algorithme de comparaison génère un rapport de comparaison. Ce rapport indiquera les différences entre les deux systèmes.
  • Réglez les différences : une fois le rapport de comparaison généré, vous devez résoudre les différences. Cela peut impliquer de mettre à jour les données dans votre CMS ou du côté de Google Play à l'aide des points de terminaison de gestion du catalogue de l'API Developer, selon la façon dont vous mettez normalement à jour votre catalogue. Pour synchroniser les produits qui ne le sont pas, utilisez les points de terminaison de mise à jour, comme décrit dans la section "Mises à jour des produits".

Arrêt du produit

L'API Google Play Developer fournit les méthodes suivantes pour vous aider à abandonner vos produits :

Pour les produits ponctuels :

Pour les produits sur abonnement :

Il peut être nécessaire d'abandonner un produit dans différents scénarios, par exemple :

  • Création par erreur.
  • Nous abandonnons une fonctionnalité ou un service.

Nous vous recommandons d'intégrer la suppression de produits à votre stratégie de gestion de catalogue.