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 capacités de serveur à serveur en tant que :

Distributeur d'applications	Développeur individuel
Enregistrez un nom de package et une clé au nom du développeur qui publie une application sur le Play Store. Enregistrez un nom de package avec une clé gérée par le Play Store. Prouvez que vous êtes propriétaire d'une clé associée à un nom de package.	Enregistrez un nom de package et une clé dans vos workflows de déploiement continu. Prouvez 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. Un accès administrateur à un projet Google Cloud.
2. Une compréhension de base des éléments suivants :
   • API RESTful
   • Structure des APK
   • Signature d'applications Android
   • Génération de condensés SHA-256

Vous devez également connaître les termes suivants :

Terme	Définition
Compte de développeur	Représente un compte Android Developer Console qui peut posséder un ou plusieurs noms de packages. Il contient un état de validation (NOT_VERIFIED ou VERIFIED).
Nom du package	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é publique 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).

Premiers pas

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 la console Google Cloud.
3. Créez un projet Google Cloud.

Activer l'API dans votre projet Google Cloud

1. Ouvrez la console Google Cloud.
2. Dans le menu de navigation (☰), sélectionnez API et services > Bibliothèque.
3. Dans le menu déroulant du projet, 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 que vous avez sélectionné. Cette opération ne prend généralement qu'un instant. Une fois l'API activée, vous pouvez commencer à l'utiliser.

Authentifier l'API

Pour effectuer des appels à 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 associé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 champ d'application suivant est requis pour toutes les opérations :

Champ d'application OAuth 2.0	Description
https://www.googleapis.com/auth/androiddeveloperconsole	Afficher et gérer les noms de packages 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. Selon le type d'application et vos besoins en matière 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 (tels que les pipelines CI/CD) de s'exécuter en arrière-plan sans intervention humaine : Configuration du consentement utilisateur unique : lors de la configuration initiale, un développeur ou un titulaire du compte effectue un flux 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 en toute sécurité 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 toute invite de connexion manuelle ou d'authentification à deux facteurs.

Si vous préférez éviter de stocker des jetons d'actualisation à longue durée de vie 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 à l'aide d'un é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. Les exécutions futures nécessitent que l'utilisateur s'authentifie à nouveau.

Enregistrer un nom de package

L'enregistrement d'un nom de package est le processus d'association d'une clé à un nom de package. La manière dont une clé est enregistrée dépend du fait que vous enregistrez une clé 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 à l'enregistrement d'un nouveau nom de package, l'API renvoie une liste d'empreintes de certificats publics connus qui peuvent être enregistrés. 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 prouver que vous en êtes le propriétaire, le développeur doit également justifier l'utilisation du nom de package.

Règles d'éligibilité des clés

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 s'est enregistré, les autres doivent fournir une justification.

Valider la propriété d'une clé

Pour valider 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 des assets 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 d'une 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. L'approbation de l'enregistrement du nom de package peut prendre jusqu'à 24 heures.

Bonnes pratiques en matière d'expérience utilisateur

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

Établir un contexte d'autorisation OAuth clair

Fournir un contexte explicite avant de demander l'autorisation OAuth permet aux développeurs de comprendre pourquoi l'accès au compte est requis. Pour guider efficacement les utilisateurs, présentez une explication claire des fonctionnalités attendues 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 [nom-de-l'application]"
• Bouton d'action : bouton "Continuer avec Google" ou "Se connecter avec Google"

Identifier les comptes de développeur

1. Intégrez-vous à 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 le compte de développeur de son choix.
3. Mettez en avant le displayName du compte 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 avec un repère visuel positif (par exemple, une coche verte).
   • NOT_VERIFIED: indiquez que la validation est incomplète et limitez l'enregistrement des packages pour le compte. Vous pouvez également fournir un bouton d'incitation à l'action principal qui redirige les développeurs vers Android Developer Console lorsqu'ils sélectionnent le compte.

Si vous recevez une réponse vide, car aucun compte de développeur n'est associé au compte Google, guidez les développeurs vers Android Developer Console à l'aide d'un bouton d'incitation à l'action principal.

Gérer les noms de packages

1. Intégrez-vous au 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.

Gérer les clés

1. Appelez le point de terminaison d'API ListAndroidPackageKeys pour récupérer toutes les clés liées à un nom de package, en offrant aux développeurs une vue d'ensemble structurée (par exemple, un tableau ou une liste) pour surveiller leur état d'enregistrement.
2. Présentez le certificateFingerprintSha256 pour chaque clé à côté de 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.

1. Permettez aux développeurs d'enregistrer des clés supplémentaires sous un nom de package existant en s'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 lequel les développeurs saisissent leur nom de 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 d'API CreateAndroidPackage pour enregistrer un nom de package sous le compte de développeur, et appelez la méthode d'API GetAndroidPackageRegistrationPolicy pour déterminer les règles d'éligibilité des clés applicables.
3. En fonction de la keySelectionStrategy désignée pour le nom de 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é à enregistrer dans la liste knownKeys fournie (contenant des empreintes de certificats SHA-256), par exemple à l'aide de boutons radio. Ce flux nécessite de valider 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 : demandez au développeur de fournir directement une clé. Dans ce cas, il n'est pas nécessaire de valider la propriété de la clé.
4. Appelez la méthode d'API CreateAndroidPackageKey pour associer la clé choisie au nouveau nom de package.

Votre application peut également détecter et extraire automatiquement le nom ou la clé du package 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 qu'ils sont propriétaires, ils doivent envoyer un APK signé qui intègre le verificationToken généré par l'API.

Pour permettre de valider la propriété d'une 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 pratique "Copier dans le presse-papiers".
• 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 assets de l'application.
• Zone de dépôt pour l'envoi d'APK : proposez une zone de dépôt dédiée pour l'importation de fichiers afin de recevoir l'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 de package nécessite que les développeurs fournissent une justification commerciale complète.

Envoyez cette justification en appelant la méthode d'API JustifyAndroidPackageKeyRegistration. Assurez-vous que l'interface utilisateur de votre application comporte une zone de saisie de texte dédiée pour collecter 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 d'être approuvé et que l'enregistrement du nom de package soit terminé.

Automatiser la validation des 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 automatiquement l'appel d'API VerifyAndroidPackageKeyOwnership en son nom.

En gérant automatiquement le processus d'inclusion du jeton et 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.

Respecter les consignes relatives à la marque

Pour maintenir 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 casse

Lorsque vous référencez le produit dans des supports ou une documentation destinés aux utilisateurs, 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 Android Developer Console repose sur les services d'identité Google. Pour rester conforme aux consignes relatives à la marque des 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 suivre ces spécifications pour préserver l'identité visuelle et l'intégrité de la marque :

• Emplacement et hiérarchie du logo : n'utilisez que le logo officiel et approuvé d'Android Developer Console. Le logo doit toujours rester secondaire par rapport aux éléments de branding principaux de votre propre application pour éviter de présenter l'application comme un produit Google officiel.

• Style visuel et distorsions : l'élément doit toujours être rendu avec son format d'image entièrement contraint. Vous ne devez jamais déformer, étirer, incliner, rogner, retourner ni modifier les composants du logo. Ne modifiez pas la palette de couleurs officielle, n'inversez pas les couleurs de premier plan ou d'arrière-plan, et n'appliquez pas d'ombres portées, d'effets de halo ni de dégradés décoratifs.
• Restrictions d'utilisation : n'intégrez aucun élément de branding appartenant à Google dans les éléments de votre propre application. L'élément de 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

• Vérifier l'état d'enregistrement d'une application avec l'API d'état de l'ID de développeur Android
• S'inscrire sur Android Developer Console
• S'inscrire sur Google Play Console
• Signer votre application