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 contenant tous les produits que vous souhaitez mettre à la disposition de vos utilisateurs. Vous pouvez le faire via 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 où la coordination manuelle est peu pratique. 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 de préparation pour découvrir comment configurer l'API Google Play Developer pour votre intégration backend.

API de gestion de 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 de catalogue 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 les produits à usage unique à partir de 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é. En fonction de la façon dont vous gérez les achats de produits uniques, vous modéliserez des produits consommables (qui peuvent être achetés autant de fois que vous le souhaitez) ou des droits d'accès permanents (qui ne peuvent pas être accordés deux fois au même utilisateur). Vous pouvez décider si les produits à usage unique doivent être consommables ou non.

Produits sur abonnement

Le point de terminaison monetization.subscriptions vous aide à gérer les produits d'abonnement à partir de votre backend de développement. Vous pouvez créer, mettre à jour et supprimer des abonnements, ou contrôler leur disponibilité et leur prix par 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.

Remarque :L'API inappproducts inclut certaines anciennes fonctionnalités pour gérer les abonnements, car auparavant, tous les produits Google Play étaient gérés via ce point de terminaison. Vous ne devez plus utiliser ce point de terminaison pour gérer les produits d'abonnement. Vous devez également migrer toutes les intégrations de publication d'abonnements pour utiliser la nouvelle API monetization.subscriptions. Pour en savoir plus sur cette suppression, consultez notre article de blog.

Méthodes par lots

Les points de terminaison 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 dans 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 grands catalogues pour la création initiale de catalogues ou la réconciliation de catalogues.

Mettre à jour la latence de propagation 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 réseau ou backend. Par défaut, toutes les requêtes de modification de produit sont sensibles à la latence. Cela signifie qu'elles sont optimisées pour une propagation rapide via les systèmes backend, qui se reflète généralement sur les appareils des utilisateurs finaux en quelques minutes. Toutefois, le nombre de ces requêtes de modification 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 de mise à jour. La propagation des mises à jour tolérantes aux latences sur les appareils des utilisateurs finaux peut prendre jusqu'à 24 heures.

Configuration des quotas

Plusieurs limites de quota doivent être prises en compte lorsque vous utilisez l'API Play Developer pour gérer votre catalogue de produits:

1. Les API Google Play Developer sont limitées à 200 000 requêtes par jour par défaut. Cette limite de quota s'applique à l'agrégation de l'utilisation dans tous les points de terminaison, y compris les API de gestion de catalogue.
2. Les points de terminaison de modification de produit 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, ainsi que 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 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 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 de traitement par lot effectuant 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 quelques exemples pour comprendre l'utilisation des quotas pour différentes requêtes:

• Une seule requête get pour extraire 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 d'extraire jusqu'à 100 éléments consommera également un jeton du quota 1 et aucun jeton des quotas 2 et 3.
• Une seule requête modification pour un seul é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 implication pratique pour les utilisateurs qui n'utilisent que des méthodes de modification uniques.
• Une requête modification par lot pour 100 éléments tolérants à la latence consomme un jeton du quota 1 et un jeton du quota 2. Cette configuration de quota devrait permettre de laisser une marge suffisante pour mettre à jour votre catalogue. Toutefois, si votre algorithme n'est pas conscient de ce quota et dépasse ce taux, vous risquez de recevoir une erreur par 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 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 de catalogue sont plus susceptibles de consommer plus de quotas pour créer votre catalogue initial complet. Cela peut 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 des quotas d'API

Nous vous recommandons vivement d'optimiser la consommation de débit pour réduire le risque d'erreurs d'API. Pour implémenter cette stratégie efficacement, nous vous recommandons de suivre les bonnes pratiques suivantes:

• Choisissez la bonne stratégie de gestion du 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écessaire 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.
• Ne pas dépasser 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, une création de catalogue initiale). Si vous prévoyez que ces processus dépasseront la limite horaire, implémentez des temps d'attente 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 aux latences pour obtenir un débit plus élevé.
• Préparez-vous à l'évolutivité de manière proactive. À mesure que votre application se développe, vous devrez peut-être augmenter l'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 de manière stratégique les 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 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. Assurez-vous d'inclure les erreurs de limitation des quotas dans votre gestion des erreurs et d'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, qui fournit des informations supplémentaires sur le domaine de l'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 de 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. S'assurer que votre catalogue Google Play est toujours à jour avec les dernières informations de votre backend présente des avantages pour améliorer l'expérience utilisateur. Exemple :

• Vous pourrez consulter la liste complète des offres disponibles, et gérer les tags d'offre et de forfait de base pour influencer votre propre éligibilité et la logique de diffusion des offres.
• Vous pouvez vérifier les différents prix et les détails des 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 les produits à portée de main dans votre backend lorsque vous traiterez de nouveaux achats, sans avoir à augmenter la latence et le risque d'échec en effectuant des appels supplémentaires à l'API Google Play Developer lors des flux critiques pour l'utilisateur.

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 au fur et à mesure des modifications. Il peut arriver que vous deviez 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 convient mieux à certains cas d'utilisation qu'à d'autres. Vous pouvez avoir un ensemble de besoins qui nécessite les deux, selon la situation. Il peut arriver que vous souhaitiez modifier un produit dès que vous en avez connaissance, par exemple pour traiter une mise à jour urgente (par exemple, un prix incorrect doit être corrigé dès que possible). Vous pouvez également utiliser une synchronisation en arrière-plan périodique 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 local change

Idéalement, les mises à jour doivent être effectuées dès qu'un changement est apporté au catalogue de produits de votre backend, afin de minimiser les écarts.

Ce type de mises à jour est recommandé 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 les produits déjà en production et vendus.

Cette approche est plus simple à implémenter et vous permet de synchroniser votre catalogue avec la période de divergence de montant la plus faible.

Quand utiliser des 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 sont une bonne option dans les cas suivants:

• 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 conciliation.
• Vous disposez déjà d'un système de gestion de contenu ou de catalogue pour gérer vos produits numériques et qui met à jour votre catalogue en permanence.

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

Remarque :Vous pouvez envoyer des mises à jour de votre catalogue de produits Google Play immédiatement après toute modification, mais cela ne signifie pas nécessairement que vos utilisateurs pourront les consulter immédiatement dans l'application. Le processus peut toujours présenter une latence en raison de retards de traitement réseau ou backend. De même, même si les mises à jour périodiques sont effectuées avec un certain délai, elles peuvent toujours être conçues pour mettre à jour votre catalogue fréquemment si nécessaire, rendant vos modifications disponibles pour les utilisateurs avec une latence similaire à celle des mises à jour à la demande. De plus, le champ latencyTolerance des méthodes par lot vous permet de choisir entre l'optimisation pour une propagation rapide des mises à jour ou un débit plus élevé. En fin de compte, le choix entre ces deux options doit être basé sur vos exigences et limites spécifiques.

Créer votre catalogue de produits

Si vous avez un grand catalogue à importer sur Google Play, vous pouvez automatiser la charge initiale. Ce type de processus lourd fonctionne mieux si une stratégie périodique est combinée à des méthodes par lot tolérantes à la latence.

Créer des produits ponctuels

Pour la création initiale d'un grand catalogue de produits unique, nous vous recommandons d'utiliser la méthode inappproducts.batchUpdate 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 à la création du catalogue dans les limites de quota.

Pour les catalogues plus petits, 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 des produits". L'avantage de cette approche est qu'elle évite d'avoir à gérer l'état de votre script et qu'elle peut être redémarrée à partir de zéro en cas de problème.

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éduit le temps nécessaire à la création du catalogue dans les limites de quota.

Pour les petits catalogues d'abonnements, 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 des produits".

Toutes les méthodes précédentes créent des abonnements avec leurs forfaits de base (fournis dans l'objet "Abonnement"). 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 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 des produits uniques 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 de correctif est généralement utilisé lorsque vous ne devez 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 de 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 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 ne souhaitez mettre à jour qu'une fiche d'un produit sur abonnement, vous devez spécifier le champ listings au 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 modifier les offres de vos forfaits de base à l'aide de la méthode monetization.subscriptions.basePlans.offers.patch.

Rapprochement du catalogue

Que vous choisissiez de mettre à jour votre catalogue Google Play chaque fois que celui de votre backend change ou de façon périodique, 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 est possible qu'il ne soit pas synchronisé avec le catalogue de la configuration de vos applications sur Play. Cela peut être dû à des modifications manuelles d'urgence dans la console, à une panne 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 de divergence prolongée.

Considérations concernant le système de diff

Nous vous recommandons de créer un système de comparaison pour détecter les incohérences et réconcilier 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 inclut de connaître les 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é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 façon dont les données des deux systèmes sont comparées. Par exemple, vous pouvez faire correspondre des ID de produit et comparer les principaux attributs de l'abonnement et des forfaits et offres de base 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 en fonction des règles que vous avez définies. Pour obtenir les données du catalogue 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 de comparaison génère un rapport de différences. Ce rapport indique les différences entre les deux systèmes.
• Réconcilier 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 normalement à 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 des produits".

Abandon du produit

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. Il peut être nécessaire de supprimer un produit dans différents scénarios, par exemple:

• Création par erreur.
• Abandon d'une fonctionnalité ou d'un service

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

Abandonner les produits ponctuels

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

Abandonner les 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é.