Enregistrer des noms de packages avec l'API Android Developer Console

L'API Android Developer Console est une interface publique conçue pour permettre aux distributeurs d'applications et aux développeurs individuels d'enregistrer de manière programmatique des noms de packages dans Android Developer Console.

Vos fonctionnalités de serveur à serveur en tant que :

Distributeur d'applications Développeur individuel
Enregistrez une clé de nom de package au nom du développeur qui publie une application sur le magasin. Enregistrez un nom de package avec une clé gérée par le magasin. Prouver que vous êtes propriétaire d'une clé associée à un nom de package. Enregistrez une clé de nom de package dans vos workflows de déploiement continu. Prouver que vous êtes propriétaire d'une clé associée à un nom de package.

Avant de commencer

Avant de commencer, vous devez disposer des éléments suivants :

  1. Accès administrateur à un projet Google Cloud.
  2. Connaissances de base sur :

Vous devez également connaître les termes suivants :

Terme Définition
Compte de développeur Représente un compte Android Developer Console pouvant posséder un ou plusieurs noms de package. Il contient un état de validation (NOT_VERIFIED ou VERIFIED).
Nom du package Un nom de package Android spécifique (par exemple, com.example.app) dans un compte de développeur, qui peut être associé à une ou plusieurs clés. Il contient un état d'enregistrement (DRAFT, IN_REVIEW, REGISTERED ou PENDING_TRANSFER).
Clé Certificat/clé public spécifique utilisé pour signer un nom de package Android. Inclut le hachage SHA-256 et l'état d'enregistrement actuel (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED ou PENDING_TRANSFER).

Commencer

Pour accéder à l'API Android Developer Console, procédez comme suit :

Créer un projet Google Cloud

  1. Créez un compte Google Cloud si vous n'en avez pas déjà un.
  2. Ouvrez Google Cloud Console.
  3. Créez un projet Google Cloud.

Activer l'API dans votre projet Google Cloud

  1. Ouvrez Google Cloud Console.
  2. Dans le menu de navigation (☰), sélectionnez API et services > Bibliothèque.
  3. Dans le menu déroulant des projets, sélectionnez le projet Google Cloud dans lequel vous souhaitez activer l'API.
  4. Utilisez la barre de recherche API et services pour sélectionner API Android Developer Console.
  5. Activez l'API :
    1. Accédez à la page de présentation de l'API en la sélectionnant dans les résultats de recherche.
    2. Cliquez sur le bouton bleu "Activer". Google Cloud active l'API pour le projet sélectionné, ce qui ne prend généralement qu'un instant. Une fois l'API activée, vous pouvez commencer à l'utiliser.

Authentifier l'API

Pour appeler l'API Android Developer Console, vous devez authentifier vos requêtes à l'aide d'OAuth 2.0.

S'authentifier avec OAuth 2.0

L'API Android Developer Console nécessite une authentification OAuth 2.0 pour autoriser l'accès aux ressources du compte de développeur et aux noms de packages. Étant donné que les données du compte de développeur sont liées au compte Google d'un utilisateur plutôt qu'à un projet Google Cloud, les comptes de service, la fédération d'identité de charge de travail et les clés API ne peuvent pas être utilisés pour authentifier les requêtes API.

Champ d'application OAuth 2.0

Le niveau d'accès suivant est requis pour toutes les opérations :

Champ d'application OAuth 2.0 Description
https://www.googleapis.com/auth/androiddeveloperconsole Consulter et gérer les noms de package et les données dans vos comptes Android Developer Console

Implémenter le flux de serveur Web OAuth 2.0

Pour s'intégrer à l'API Android Developer Console, les applications doivent utiliser le flux de serveur Web OAuth 2.0. En fonction de votre type d'application et de vos besoins d'automatisation, vous pouvez choisir entre deux stratégies principales de gestion des identifiants :

Option A (recommandée) : accès hors connexion / automatisé (intégration CI/CD et serveur) Option B : Accès éphémère / interactif
Cette stratégie permet aux processus automatisés (comme les pipelines CI/CD) de s'exécuter en arrière-plan sans intervention humaine :

Configuration unique du consentement utilisateur : lors de la configuration initiale, un développeur ou un titulaire du compte effectue un parcours de consentement unique dans son navigateur. Votre application demande un accès hors connexion (access_type=offline) ainsi que le champ d'application de l'API. Google renvoie un code d'autorisation, que votre application échange contre un jeton d'accès initial et un jeton d'actualisation à longue durée de vie.

Exécution en arrière-plan : stockez de manière sécurisée le refresh_token dans votre environnement de déploiement ou votre gestionnaire de secrets (par exemple, GitHub Actions Secrets, Google Secret Manager). Pour les appels d'API suivants, votre workflow automatisé utilise le jeton d'actualisation stocké pour obtenir un nouveau jeton d'accès de courte durée à la demande, en contournant les invites de connexion manuelle ou d'A2F. 		Si vous préférez éviter de stocker des jetons d'actualisation de longue durée dans votre environnement, ou si votre application s'exécute dans un contexte utilisateur interactif :

Invite à l'exécution : ne demandez pas d'accès hors connexion et ne stockez pas de jeton d'actualisation. Chaque fois que l'outil ou l'application est exécuté, invitez l'utilisateur à s'authentifier en le redirigeant vers la page de consentement Google OAuth dans son navigateur.

Accès de courte durée : l'utilisateur se connecte et donne son consentement, et l'application reçoit directement un jeton d'accès de courte durée (ou utilise l'échange de code d'autorisation). Ce jeton d'accès est utilisé pour effectuer des appels d'API et est supprimé après l'exécution. Pour les exécutions ultérieures, l'utilisateur doit se réauthentifier.

Enregistrer un nom de package

L'enregistrement d'un nom de package consiste à associer une clé à un nom de package. La façon dont une clé est enregistrée dépend de si vous l'enregistrez pour un nom de package nouveau ou existant dans Android.

Enregistrer un nouveau nom de package

Pour un nouveau nom de package jamais enregistré sur Android, vous pouvez fournir le certificat de clé publique de la paire de clés de signature de l'application.

Enregistrer un nom de package existant

Pour enregistrer un nom de package existant, vous devez prouver que vous êtes propriétaire d'une clé de signature privée connue. Contrairement à lors de l'enregistrement d'un nouveau nom de package, l'API renvoie une liste des empreintes des certificats publics connus éligibles à l'enregistrement. Ces clés peuvent être utilisées pour effectuer un enregistrement direct.

Si la clé que vous enregistrez est listée comme "nécessitant une justification", vous pouvez toujours l'enregistrer. Toutefois, en plus de fournir une preuve de propriété, le développeur doit également justifier l'utilisation du nom de package.

Principales règles d'éligibilité

La liste des clés éligibles est déterminée par les règles d'éligibilité des noms de packages, conçues pour minimiser le partage de noms de packages (ces règles ont été introduites dans le cadre de la validation des développeurs Android).

Dans les cas où un nom de package est utilisé par plusieurs développeurs ou comporte plusieurs clés de signature, l'éligibilité est déterminée comme suit :

Scénario Règle pour l'enregistrement direct Règle pour les autres développeurs
Propriétaire principal La clé qui représente plus de 50 % du nombre total d'installations connues est prioritaire. Tous les autres développeurs doivent fournir une justification.
Plus de 50 installations Si aucune clé n'est associée à plus de 50 % des installations, toutes les clés comptant au moins 50 installations sont éligibles. Les développeurs dont les clés comptent moins de 50 installations doivent fournir une justification.
Moins de 50 installations Si aucune clé n'atteint le seuil des 50 installations, n'importe quelle clé peut être utilisée selon le principe du premier arrivé, premier servi. Une fois qu'un développeur a effectué l'enregistrement, les autres doivent fournir une justification.

Valider la propriété de la clé

Pour terminer la validation d'un nom de package existant, l'API fournit une chaîne de validation. Cette chaîne de validation doit être incluse dans un nouveau fichier nommé adi-registration.properties dans le dossier d'éléments de l'application. Vous devez ensuite signer et importer l'APK à l'aide de la clé privée correspondant à la clé publique que vous enregistrez.

Justifier l'enregistrement de la clé

Si l'enregistrement d'une clé nécessite une justification, les développeurs doivent fournir une justification commerciale détaillée. Google examine cette justification, et l'approbation de l'enregistrement du nom du package peut prendre jusqu'à 24 heures.

Bonnes pratiques concernant l'expérience utilisateur

Il est recommandé que les applications utilisant l'API Android Developer Console suivent ces modèles pour garantir une intégration parfaite.

Établir un contexte d'autorisation OAuth clair

Fournir un contexte explicite avant de demander l'autorisation OAuth aide les développeurs à comprendre pourquoi l'accès au compte est requis. Pour guider efficacement les utilisateurs, présentez une explication claire de la fonctionnalité attendue avant de lancer l'écran de consentement OAuth.

Structurez le contexte d'autorisation au format suivant :

  • Titre : "Associer votre compte Android Developer Console"
  • Résumé : "Gérer l'enregistrement des noms de packages pour la validation des développeurs Android dans [application-name]"
  • Bouton d'action : bouton "Continuer avec Google" ou "Se connecter avec Google"
Boîte de dialogue illustrant le contexte d'autorisation OAuth pour l'association d'un compte.
Figure 1. Associez votre compte Android Developer Console.

Identifier les comptes de développeur

  1. Intégrez la méthode d'API ListDeveloperAccounts pour récupérer et lister tous les comptes de développeur pour lesquels l'accès a été autorisé.
  2. Fournissez un sélecteur de compte pour permettre au développeur de choisir son compte de développeur préféré.
  3. Mettez en avant le compte displayName, en utilisant le numéro de compte du champ name comme information secondaire.
  4. Affichez les états de validation du compte (verificationState) :
    • VERIFIED : confirmez l'identité validée du développeur à l'aide d'un repère visuel positif (par exemple, une coche verte).
    • NOT_VERIFIED : indique que la validation est incomplète et limite l'enregistrement de packages pour le compte. Vous pouvez éventuellement fournir un bouton d'incitation à l'action principal qui redirige les développeurs vers la console Android Developer lorsqu'ils sélectionnent le compte.
Sélecteur de compte affichant le nom du compte de développeur et l'état de validation.
Figure 2. Outil de sélection de comptes affichant les comptes de développeur et l'état de validation.

Si une réponse vide est reçue, car aucun compte de développeur n'est associé au compte Google, redirigez les développeurs vers la console Android Developer Console à l'aide d'un bouton d'incitation à l'action principal.

Gérer les noms de packages

  1. Intégrez le point de terminaison de l'API ListAndroidPackages pour récupérer tous les noms de packages associés au compte de développeur. Fournissez aux développeurs une interface centralisée, telle qu'une liste ou un tableau, pour surveiller efficacement l'état de leurs packages.
  2. Affichez le packageName à côté de son état d'enregistrement actuel (DRAFT, IN_REVIEW, REGISTERED ou PENDING_TRANSFER), en appliquant des indicateurs visuels distincts pour chaque état. Si un "nom convivial" a été fourni et enregistré lors de la création, vous pouvez éventuellement l'inclure dans l'affichage.
Interface affichant les noms des packages enregistrés et leur état.
Figure 3 : Interface permettant de gérer les noms de packages et les états d'enregistrement.

Gérer les clés

  1. Appelez le point de terminaison de l'API ListAndroidPackageKeys pour récupérer toutes les clés associées à un nom de package, ce qui offre aux développeurs un aperçu structuré (comme un tableau ou une liste) pour surveiller l'état de leur enregistrement.
  2. Présentez le certificateFingerprintSha256 de chaque clé ainsi que son état d'enregistrement (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE ou PENDING_TRANSFER) en utilisant des indicateurs visuels distincts pour différencier les états.
Liste des empreintes de certificat et des états d'enregistrement des clés.
Figure 4. Présentation des clés et de leur état d'enregistrement.
  1. Permettez aux développeurs d'enregistrer des clés supplémentaires sous un nom de package existant en intégrant la méthode d'API CreateAndroidPackageKey.

Enregistrer un nom de package

  1. Utilisez une mise en page basée sur un formulaire dans laquelle les développeurs saisissent le nom de leur package dans un champ de texte, à condition que ces informations n'aient pas déjà été collectées par votre application (par exemple, via une invite précédente).
  2. Appelez la méthode API CreateAndroidPackage pour enregistrer un nom de package sous le compte de développeur, puis appelez la méthode API GetAndroidPackageRegistrationPolicy pour déterminer les règles d'éligibilité des clés applicables.
  3. En fonction du keySelectionStrategy désigné pour le nom du package, invitez le développeur à effectuer l'une des opérations suivantes :
    • Si keySelectionStrategy est défini sur SELECT_KEY_FROM_LIST : demandez au développeur de choisir une clé pour l'enregistrement dans la liste knownKeys fournie (contenant les empreintes du certificat SHA-256), par exemple à l'aide de cases d'option. Ce flux nécessite la validation de la propriété de la clé (voir Valider la propriété d'une clé ci-dessous).
    • Si keySelectionStrategy est défini sur USE_ANY_KEY : invitez le développeur à fournir une clé directement. La validation de la propriété de la clé n'est pas nécessaire dans ce cas.
  4. Appelez la méthode API CreateAndroidPackageKey pour associer la clé choisie au nouveau nom de package.
Formulaire permettant d'enregistrer le nom du package et de sélectionner la clé de signature.
Figure 5. Processus d'enregistrement d'un nom de package et de sélection d'une clé.

Votre application peut également détecter et extraire automatiquement le nom du package ou la clé directement à partir d'une application importée.

Valider la propriété d'une clé

Lorsque keySelectionStrategy est défini sur SELECT_KEY_FROM_LIST, les développeurs doivent prouver qu'ils sont propriétaires de leur clé de signature privée. Pour prouver que vous êtes propriétaire, vous devez envoyer un APK signé qui intègre le verificationToken généré par l'API.

Pour permettre la validation de la propriété de la clé, intégrez la méthode d'API VerifyAndroidPackageKeyOwnership et créez les composants d'interface utilisateur suivants :

  • Composant d'affichage du jeton : affichez le verificationToken de manière visible dans un bloc d'extrait de code, y compris un bouton "Copier dans le presse-papiers" pratique.
  • Instructions de configuration pour les développeurs : fournissez des instructions détaillées indiquant au développeur de placer un fichier adi-registration.properties contenant le verificationToken dans le dossier des éléments de l'application.
  • Zone de dépôt pour l'envoi de l'APK : proposez une zone de dépôt dédiée à l'importation de fichiers pour recevoir l'APK signé.
Zone de dépôt et affichage du jeton pour vérifier la propriété de la clé.
Figure 6. Composants d'interface utilisateur permettant de valider la propriété de la clé avec l'importation d'un APK signé.

Justifier l'enregistrement d'une clé

Lorsqu'une clé connue a son champ justificationRequired défini sur REQUIRED, l'enregistrement de cette clé avec le nom du package nécessite que les développeurs fournissent une justification commerciale détaillée.

Envoyez cette justification en appelant la méthode API JustifyAndroidPackageKeyRegistration. Assurez-vous que l'interface utilisateur de votre application comporte une zone de saisie de texte dédiée pour recueillir la justification du développeur, et informez-le qu'il doit fournir une justification avant d'envoyer la demande d'enregistrement de la clé. Google examine la justification envoyée. Ce processus peut prendre jusqu'à 24 heures avant que l'enregistrement du nom de package ne soit terminé.

Automatiser la validation des clés pour les clés gérées

Si votre application gère la clé de signature d'un développeur, celui-ci ne peut pas signer manuellement un APK pour valider la propriété. Vous devez plutôt exécuter l'appel d'API VerifyAndroidPackageKeyOwnership automatiquement en leur nom.

En gérant automatiquement l'inclusion du jeton et le processus d'importation de l'APK, votre application supprime ces étapes manuelles. Veillez à informer les développeurs que la validation de la propriété de la clé est gérée de manière transparente par votre application à l'aide de la clé stockée dans votre système.

Suivre les consignes relatives à la marque

Pour préserver la confiance des utilisateurs et garantir la transparence, toutes les applications qui s'intègrent à l'API Android Developer Console doivent respecter les consignes relatives à la marque suivantes.

Terminologie et utilisation des majuscules

Lorsque vous faites référence au produit dans des documents ou de la documentation visibles par l'utilisateur, utilisez toujours le nom complet "Android Developer Console". N'utilisez pas l'abréviation "ADC".

Le programme doit être appelé "validation des développeurs Android". Respectez exactement cette casse et cette orthographe dans tous les contextes.

Pour éviter toute ambiguïté avec les APK ou les AAB, utilisez spécifiquement le terme "nom de package" plutôt que simplement "package".

Lorsque vous décrivez le processus d'ajout d'un nom de package, utilisez l'expression "enregistrer un nom de package" au lieu de "revendiquer un nom de package".

Utiliser l'incitation à l'action "Se connecter"

L'authentification OAuth 2.0 avec la console Android Developer s'appuie sur Google Identity Services. Pour respecter les consignes relatives à la marque Google Identity Services, vous devez utiliser l'incitation à l'action "Continuer avec Google" ou "Se connecter avec Google" sur le bouton d'autorisation. Ce texte est obligatoire et ne peut pas être modifié, car il permet aux utilisateurs de comprendre qu'ils utilisent leurs identifiants Google pour autoriser votre application à accéder à leur compte Google.

Maintenir l'identité et l'intégrité de la marque

Lorsque vous intégrez le logo Android Developer Console à l'interface de votre application, vous devez respecter les spécifications suivantes pour préserver l'identité visuelle et l'intégrité de la marque :

  • Emplacement et hiérarchie du logo : utilisez uniquement le logo officiel et approuvé d'Android Developer Console. Le logo doit toujours rester secondaire par rapport aux éléments distinctifs principaux de votre application afin d'éviter de présenter l'application comme un produit Google officiel.
Logo officiel d'Android Developer Console. Cliquez pour enregistrer le fichier.
Figure 7. Logo officiel d'Android Developer Console. Cliquez sur l'image pour enregistrer le fichier.
  • Style visuel et distorsions : l'asset doit toujours être affiché avec un format entièrement contraint. Vous ne devez jamais déformer, étirer, incliner, recadrer, retourner ni modifier les composants du logo. Ne modifiez pas la palette de couleurs officielle, n'intervertissez pas les couleurs de premier plan et d'arrière-plan, et n'appliquez pas d'ombres portées, d'effets de lueur ni de dégradés décoratifs.
  • Restrictions d'utilisation : n'intégrez aucun élément distinctif appartenant à Google dans les éléments de votre propre application. Le logo Android Developer Console ne peut être utilisé que dans le contexte de la mise en page de l'application pour indiquer explicitement une intégration active.

Ressources supplémentaires