Registrare i nomi di pacchetto con l'API Android Developer Console

L'API Android Developer Console è un'interfaccia pubblica progettata per consentire ai distributori di app e ai singoli sviluppatori di registrare in modo programmatico i nomi dei pacchetti in Android Developer Console.

Le tue funzionalità server-to-server come:

App Distribution Sviluppatore privato
Registra una chiave per il nome del pacchetto per conto dello sviluppatore che pubblica un'app nello store. Registra un nome di pacchetto con una chiave gestita dallo store. Dimostrare la proprietà di una chiave associata a un nome del pacchetto. Registra una chiave per il nome del pacchetto nei workflow di deployment continuo. Dimostrare la proprietà di una chiave associata a un nome del pacchetto.

Prima di iniziare

Prima di iniziare, devi avere:

  1. Accesso amministrativo a un progetto Google Cloud.
  2. Conoscenza di base di:

Dovresti anche avere familiarità con i seguenti termini:

Termine Definizione
Account sviluppatore Rappresenta un account Android Developer Console che può possedere uno o più nomi pacchetto. Contiene uno stato di verifica (NOT_VERIFIED o VERIFIED).
Nome pacchetto Un nome di pacchetto Android specifico (ad esempio com.example.app) all'interno di un account sviluppatore, che può essere associato a una o più chiavi. Contiene uno stato di registrazione (DRAFT, IN_REVIEW, REGISTERED o PENDING_TRANSFER).
Chiave Il certificato/la chiave pubblica specifici utilizzati per firmare un nome di pacchetto Android. Include l'hash SHA-256 e lo stato di registrazione corrente (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED o PENDING_TRANSFER).

Inizia

Per accedere all'API Android Developer Console, completa i seguenti passaggi:

Creare un progetto Google Cloud

  1. Crea un account Google Cloud se non ne hai già uno.
  2. Apri la console Google Cloud.
  3. Crea un progetto Google Cloud.

Abilita l'API nel tuo progetto Google Cloud

  1. Apri la console Google Cloud.
  2. Nel menu di navigazione (☰), seleziona API e servizi > Libreria.
  3. Seleziona il progetto cloud in cui vuoi abilitare l'API dal menu a discesa dei progetti.
  4. Utilizza la barra di ricerca API e servizi per selezionare Android Developer Console API.
  5. Abilita l'API:
    1. Vai alla pagina di riepilogo dell'API selezionandola dai risultati di ricerca.
    2. Fai clic sul pulsante blu Abilita. Google Cloud attiva l'API per il progetto selezionato, il che di solito richiede solo un momento. Una volta attivata, puoi iniziare a utilizzarla.

Autentica l'API

Per effettuare chiamate all'API Android Developer Console, devi autenticare le tue richieste utilizzando OAuth 2.0.

Esegui l'autenticazione con OAuth 2.0

L'API Android Developer Console richiede l'autenticazione OAuth 2.0 per autorizzare l'accesso alle risorse dell'account sviluppatore e ai nomi di pacchetto. Poiché i dati dell'account sviluppatore sono collegati all'Account Google di un utente anziché a un progetto Google Cloud, non è possibile utilizzare service account, federazione delle identità per i workload e chiavi API per autenticare le richieste API.

Ambito OAuth 2.0

Il seguente ambito è obbligatorio per tutte le operazioni:

Ambito OAuth 2.0 Descrizione
https://www.googleapis.com/auth/androiddeveloperconsole Visualizzare e gestire i nomi dei pacchetti e i dati nei tuoi account Android Developer Console

Implementa il flusso del server web OAuth 2.0

Per l'integrazione con l'API Android Developer Console, le applicazioni devono utilizzare il flusso del server web OAuth 2.0. A seconda del tipo di applicazione e delle esigenze di automazione, puoi scegliere tra due strategie principali di gestione delle credenziali:

Opzione A (consigliata): accesso offline / automatico (integrazione CI/CD e server) Opzione B: accesso temporaneo / interattivo
Questa strategia consente ai processi automatizzati (come le pipeline CI/CD) di essere eseguiti in background senza l'intervento umano:

Configurazione del consenso dell'utente una tantum: durante la configurazione iniziale, uno sviluppatore o un proprietario dell'account completa un flusso di consenso una tantum nel proprio browser. La tua applicazione richiede l'accesso offline (access_type=offline) insieme all'ambito dell'API. Google restituisce un codice di autorizzazione, che la tua applicazione scambia con un token di accesso iniziale e un token di aggiornamento di lunga durata.

Esecuzione in background: archivia in modo sicuro la refresh_token nel tuo ambiente di deployment o gestore di secret (ad esempio, GitHub Actions Secrets, Google Secret Manager). Per le chiamate API successive, il tuo workflow automatizzato utilizza il token di aggiornamento archiviato per ottenere un nuovo token di accesso di breve durata on demand, bypassando qualsiasi richiesta di accesso manuale o di autenticazione a due fattori. 		Se preferisci evitare di archiviare token di aggiornamento di lunga durata nel tuo ambiente o se la tua applicazione viene eseguita in un contesto utente interattivo:

Prompt on execution: non richiedere l'accesso offline o l'archiviazione di un token di aggiornamento. Ogni volta che lo strumento o l'applicazione viene eseguito, chiedi all'utente di autenticarsi reindirizzandolo alla pagina di consenso OAuth di Google nel browser.

Accesso di breve durata: l'utente accede e dà il consenso, mentre l'applicazione riceve direttamente un token di accesso di breve durata (o utilizza lo scambio di codici di autorizzazione). Questo token di accesso viene utilizzato per effettuare chiamate API e viene eliminato dopo l'esecuzione. Per le esecuzioni future, l'utente dovrà eseguire nuovamente l'autenticazione.

Registra un nome di pacchetto

La registrazione del nome del pacchetto è la procedura di associazione di una chiave a un nome del pacchetto. La modalità di registrazione di una chiave dipende dal fatto che tu stia registrando una chiave per un nome di pacchetto nuovo o esistente in Android.

Registra un nuovo nome di pacchetto

Per un nuovo nome di pacchetto mai visto su Android, puoi fornire il certificato di chiave pubblica dalla coppia di chiavi di firma dell'app.

Registra un nome di pacchetto esistente

Per registrare un nome di pacchetto esistente, devi dimostrare la proprietà di una chiave di firma privata nota. A differenza di quando registri un nuovo pacchetto, l'API restituisce un elenco di fingerprint dei certificati pubblici noti idonei per la registrazione. Queste chiavi possono essere utilizzate per la registrazione diretta.

Se la chiave che stai registrando è elencata come "richiede giustificazione", puoi comunque registrarla, ma oltre a completare la prova di proprietà, lo sviluppatore deve anche inviare una giustificazione per l'utilizzo del nome di pacchetto.

Regole di idoneità principali

L'elenco delle chiavi idonee è determinato dalle regole di idoneità del nome di pacchetto progettate per ridurre al minimo l'utilizzo dello stesso nome di pacchetto (introdotte nell'ambito della verifica dello sviluppatore Android).

Nei casi in cui un nome di pacchetto viene utilizzato da più sviluppatori o ha più chiavi di firma, l'idoneità viene determinata nel seguente modo:

Scenario Regola per la registrazione diretta Regola per gli altri sviluppatori
Titolare della maggioranza delle chiavi La chiave che rappresenta oltre il 50% delle installazioni note totali ha la priorità. Tutti gli altri sviluppatori devono fornire una motivazione.
50+ installazioni Se nessuna chiave ha più del 50% delle installazioni, tutte le chiavi con 50 o più installazioni sono idonee. Gli sviluppatori con chiavi con meno di 50 installazioni devono fornire una motivazione.
Meno di 50 installazioni Se nessuna chiave raggiunge la soglia di 50 installazioni, qualsiasi chiave può essere utilizzata in ordine di arrivo. Una volta che uno sviluppatore si è registrato, gli altri devono fornire una motivazione.

Verifica la proprietà della chiave

Per completare la verifica di un nome di pacchetto esistente, l'API fornisce una stringa di verifica. Questa stringa di verifica deve essere inclusa in un nuovo file denominato adi-registration.properties all'interno della cartella degli asset dell'app. Devi quindi firmare e caricare l'APK utilizzando la chiave privata corrispondente alla chiave pubblica che stai registrando.

Giustifica la registrazione della chiave

Se la registrazione di una chiave richiede una motivazione, gli sviluppatori devono inviare una motivazione aziendale dettagliata. Google esamina questa motivazione e l'approvazione della registrazione del nome del pacchetto può richiedere fino a 24 ore.

Best practice per l'esperienza utente

Per un'integrazione perfetta, è consigliabile che le applicazioni che utilizzano l'API Android Developer Console seguano questi pattern.

Stabilisci un contesto di autorizzazione OAuth chiaro

Fornire un contesto esplicito prima di richiedere l'autorizzazione OAuth aiuta gli sviluppatori a capire perché è necessario l'accesso all'account. Per guidare gli utenti in modo efficace, presenta una spiegazione chiara della funzionalità prevista prima di lanciare la schermata per il consenso OAuth.

Struttura il contesto di autorizzazione utilizzando il seguente formato:

  • Titolo: "Collega il tuo account Android Developer Console"
  • Riepilogo: "Gestisci la registrazione del nome di pacchetto per la verifica dello sviluppatore Android all'interno di [application-name]"
  • Pulsante di azione: pulsante "Continua con Google" o "Accedi con Google"
Finestra di dialogo che illustra il contesto di autorizzazione OAuth per il collegamento di un account.
Figura 1. Collega il tuo account Android Developer Console.

Identifica gli account sviluppatore

  1. Esegui l'integrazione con il metodo API ListDeveloperAccounts per recuperare ed elencare tutti gli account sviluppatore per cui è stato autorizzato l'accesso.
  2. Fornisci un selettore account per consentire allo sviluppatore di scegliere l'account sviluppatore che preferisce.
  3. Metti in evidenza il conto displayName, utilizzando il numero di conto bancario del campo name come informazione secondaria.
  4. Visualizza gli stati di verifica dell'account (verificationState):
    • VERIFIED: conferma l'identità dello sviluppatore verificato con un indicatore visivo positivo (ad es. un segno di spunta verde).
    • NOT_VERIFIED: indica che la verifica non è completa e limita la registrazione dei pacchetti per l'account. Se vuoi, fornisci un pulsante CTA principale che indirizzi gli sviluppatori ad Android Developer Console dopo aver selezionato l'account.
Selettore account che mostra il nome dell'account sviluppatore e lo stato della verifica.
Figura 2. Selettore account che mostra gli account sviluppatore e lo stato della verifica.

Se viene ricevuta una risposta vuota perché non sono presenti account sviluppatore associati all'Account Google, indirizza gli sviluppatori ad Android Developer Console utilizzando un pulsante CTA principale.

Gestisci i nomi dei pacchetti

  1. Esegui l'integrazione con l'endpoint API ListAndroidPackages per recuperare tutti i nomi dei pacchetti associati all'account sviluppatore. Fornisci agli sviluppatori un'interfaccia centralizzata, ad esempio un elenco o una tabella, per monitorare in modo efficace gli stati dei pacchetti.
  2. Visualizza packageName insieme allo stato di registrazione corrente (DRAFT, IN_REVIEW, REGISTERED o PENDING_TRANSFER), applicando indicatori visivi distinti per ogni stato. Se durante la creazione è stato fornito e salvato un "nome descrittivo", puoi includerlo facoltativamente nella visualizzazione.
Interfaccia che mostra i nomi dei pacchetti registrati e i relativi stati.
Figura 3. Interfaccia per la gestione dei nomi dei pacchetti e degli stati di registrazione.

Gestisci chiavi

  1. Chiama l'endpoint API ListAndroidPackageKeys per recuperare tutte le chiavi associate a un nome di pacchetto, offrendo agli sviluppatori una panoramica strutturata (ad esempio una tabella o un elenco) per monitorare lo stato della registrazione.
  2. Presenta il certificateFingerprintSha256 per ogni chiave insieme al suo stato di registrazione (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE o PENDING_TRANSFER), utilizzando indicatori visivi distinti per differenziare gli stati.
Elenco dei fingerprint dei certificati e degli stati di registrazione delle chiavi.
Figura 4. Panoramica delle chiavi e dei relativi stati di registrazione.
  1. Consenti agli sviluppatori di registrare chiavi aggiuntive con un nome di pacchetto esistente tramite l'integrazione con il metodo API CreateAndroidPackageKey.

Registra un nome di pacchetto

  1. Utilizza un layout basato su modulo in cui gli sviluppatori inseriscono il nome del pacchetto in un campo di testo, a condizione che queste informazioni non siano già state raccolte dalla tua applicazione (ad esempio tramite un prompt precedente).
  2. Chiama il metodo API CreateAndroidPackage per registrare un nome del pacchetto nell'account sviluppatore e chiama il metodo API GetAndroidPackageRegistrationPolicy per determinare le regole di idoneità delle chiavi applicabili.
  3. In base al keySelectionStrategy designato per il nome del pacchetto, chiedi allo sviluppatore di eseguire una delle seguenti operazioni:
    • Se keySelectionStrategy è impostato su SELECT_KEY_FROM_LIST: chiedi allo sviluppatore di scegliere una chiave per la registrazione dall'elenco knownKeys fornito (contenente le fingerprint del certificato SHA-256), ad esempio utilizzando i pulsanti di opzione. Questo flusso richiede la verifica della proprietà della chiave (consulta Verifica la proprietà di una chiave di seguito).
    • Se keySelectionStrategy è impostato su USE_ANY_KEY: chiedi allo sviluppatore di fornire direttamente una chiave. In questo caso, la verifica della proprietà della chiave non è necessaria.
  4. Chiama il metodo API CreateAndroidPackageKey per associare la chiave scelta al nuovo nome del pacchetto.
Modulo per la registrazione del nome pacchetto e la selezione della chiave di firma.
Figura 5. Flusso per la registrazione di un nome pacchetto e la selezione di una chiave.

In alternativa, l'applicazione può rilevare ed estrarre automaticamente il nome del pacchetto o la chiave direttamente da un'app caricata.

Verifica la proprietà di una chiave

Quando keySelectionStrategy è impostato su SELECT_KEY_FROM_LIST, gli sviluppatori devono dimostrare la proprietà della propria chiave di firma privata. La prova di proprietà richiede l'invio di un APK firmato che incorpora il valore verificationToken generato dall'API.

Per supportare la verifica della proprietà delle chiavi, integra il metodo API VerifyAndroidPackageKeyOwnership e crea i seguenti componenti dell'interfaccia utente:

  • Componente di visualizzazione del token: mostra il verificationToken in evidenza all'interno di un blocco di snippet di codice, incluso un pratico pulsante "Copia negli appunti".
  • Istruzioni di configurazione per gli sviluppatori:fornisci istruzioni dettagliate che indichino allo sviluppatore di inserire un file adi-registration.properties contenente verificationToken nella cartella degli asset dell'app.
  • Zona di rilascio per l'invio dell'APK:offri una zona di rilascio dedicata per il caricamento dei file per ricevere l'APK firmato.
Zona di rilascio e visualizzazione del token per la verifica della proprietà della chiave.
Figura 6. Componenti UI per la verifica della proprietà della chiave con il caricamento dell'APK firmato.

Giustifica la registrazione di una chiave

Quando una chiave nota ha il campo justificationRequired impostato su REQUIRED, per registrarla insieme al nome del pacchetto gli sviluppatori devono inviare una motivazione aziendale dettagliata.

Invia questa motivazione chiamando il metodo API JustifyAndroidPackageKeyRegistration. Assicurati che l'interfaccia utente della tua applicazione disponga di un'area di immissione di testo dedicata per raccogliere la motivazione dello sviluppatore e informalo che è necessario fornire una motivazione prima di inviare la richiesta di registrazione della chiave. Google esamina la motivazione inviata, un processo che può richiedere fino a 24 ore per l'approvazione prima che la registrazione del nome del pacchetto sia completata.

Automatizza la verifica delle chiavi per le chiavi gestite

Se la tua applicazione gestisce la chiave di firma di uno sviluppatore, quest'ultimo non può firmare manualmente un APK per la verifica della proprietà. Devi invece eseguire automaticamente la chiamata API VerifyAndroidPackageKeyOwnership per loro conto.

Gestendo automaticamente l'inclusione dei token e il processo di caricamento degli APK, la tua applicazione rimuove questi passaggi manuali. Assicurati di informare gli sviluppatori che la verifica della proprietà delle chiavi è gestita senza problemi dalla tua applicazione utilizzando la chiave archiviata nel tuo sistema.

Segui le linee guida per il brand

Per mantenere la fiducia degli utenti e garantire la trasparenza, tutte le applicazioni che si integrano con l'API Android Developer Console devono rispettare le seguenti linee guida per il brand.

Terminologia e lettere maiuscole

Quando fai riferimento al prodotto in materiali o documentazione rivolti agli utenti, utilizza sempre il nome completo Android Developer Console. Non utilizzare l'abbreviazione "ADC".

Il programma deve essere denominato "verifica dello sviluppatore Android". Utilizza questa esatta combinazione di maiuscole e minuscole e questa ortografia in tutti i contesti.

Per evitare ambiguità con gli APK o gli AAB, utilizza il termine "nome del pacchetto" in modo specifico anziché solo "pacchetto".

Quando descrivi la procedura di aggiunta di un nome di pacchetto, utilizza la frase "registra un nome di pacchetto" anziché "rivendica un nome di pacchetto".

Utilizza l'invito all'azione "Accedi"

L'autenticazione OAuth 2.0 con Android Developer Console si basa su Servizi di identità Google. Per rispettare le linee guida per il branding dei Servizi di identità Google, devi utilizzare l'invito all'azione "Continua con Google" o "Accedi con Google" sul pulsante di autorizzazione. Questo testo è obbligatorio e non può essere modificato, in quanto garantisce che gli utenti comprendano che stanno utilizzando le proprie credenziali Google per autorizzare la tua applicazione ad accedere al loro Account Google.

Mantieni l'identità e l'integrità del brand

Quando integri il logo di Android Developer Console nell'interfaccia della tua applicazione, devi seguire queste specifiche per preservare l'identità visiva e l'integrità del brand:

  • Posizionamento e gerarchia del logo:utilizza solo il logo ufficiale e approvato di Android Developer Console. Il logo deve sempre rimanere secondario rispetto agli elementi distintivi del brand principali della tua applicazione per evitare di rappresentare erroneamente l'applicazione come un prodotto Google ufficiale.
Logo ufficiale di Android Developer Console. Fai clic per salvare il file.
Figura 7. Logo ufficiale di Android Developer Console. Fai clic sull'immagine per salvare il file.
  • Stile visivo e distorsioni: l'asset deve essere sempre visualizzato con le proporzioni completamente vincolate. Non devi mai distorcere, allungare, inclinare, ritagliare, capovolgere o modificare i componenti del logo. Non modificare la tavolozza dei colori ufficiale, non scambiare i colori di primo piano o di sfondo e non applicare ombre, effetti di luce o gradienti decorativi.
  • Limitazioni di utilizzo: non incorporare elementi di branding di proprietà di Google negli asset della tua applicazione. L'asset del logo di Android Developer Console può essere utilizzato solo nel contesto del layout dell'applicazione per indicare esplicitamente un'integrazione attiva.

Risorse aggiuntive