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:

Distributore di app Singolo sviluppatore
Registra un nome di pacchetto - chiave per conto dello sviluppatore che pubblica un'app nello store. Registra un nome di pacchetto con una chiave gestita dallo store. Dimostra la proprietà di una chiave associata a un nome di pacchetto. Registra un nome di pacchetto - chiave nei workflow di deployment continuo. Dimostra la proprietà di una chiave associata a un nome di pacchetto.

Prima di iniziare

Prima di iniziare, devi avere:

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

Dovresti anche conoscere i seguenti termini:

Termine Definizione
Account sviluppatore Rappresenta un account Android Developer Console che può essere proprietario di uno o più nomi di pacchetto. Contiene uno stato di verifica (NOT_VERIFIED o VERIFIED).
Nome pacchetto Un nome di pacchetto Android specifico (ad es. 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 La chiave/il certificato pubblico specifico utilizzato 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.

Abilitare l'API nel progetto Google Cloud

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

Autenticare l'API

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

Autenticare 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 dei pacchetti. 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 Visualizza e gestisci i nomi dei pacchetti e i dati nei tuoi account Android Developer Console

Implementare 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 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 browser. La tua applicazione richiede l'accesso offline (access_type=offline) insieme all'ambito 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 il refresh_token nell'ambiente di deployment o nel gestore dei secret (ad es. GitHub Actions Secrets, Google Secret Manager). Per le chiamate API successive, il workflow automatizzato utilizza il token di aggiornamento archiviato per ottenere un nuovo token di accesso di breve durata on demand, ignorando eventuali richieste di accesso manuale o 2FA. 		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:

Richiesta all'esecuzione: non richiedere l'accesso offline né archiviare 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 fornisce il consenso e l'applicazione riceve un token di accesso di breve durata direttamente (o utilizzando lo scambio di codici di autorizzazione). Questo token di accesso viene utilizzato per effettuare chiamate API e viene eliminato dopo l'esecuzione. Le esecuzioni future richiedono la riautenticazione dell'utente.

Registrare un nome di pacchetto

La registrazione del nome del pacchetto è il processo di associazione di una chiave a un nome di 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.

Registrare 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.

Registrare 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 di certificati pubblici noti idonei alla registrazione. Queste chiavi possono essere utilizzate per la registrazione diretta.

Se la chiave che stai registrando è elencata come "richiede una giustificazione", puoi comunque registrarla, ma oltre a completare la dimostrazione della proprietà, lo sviluppatore è tenuto a fornire una giustificazione per l'utilizzo del nome del pacchetto.

Regole di idoneità delle chiavi

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 giustificazione.
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 giustificazione.
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 giustificazione.

Verificare 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. Dopodiché devi firmare e caricare l'APK utilizzando la chiave privata corrispondente alla chiave pubblica che stai registrando.

Giustificare la registrazione della chiave

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

Best practice per l'esperienza utente

È consigliabile che le applicazioni che utilizzano l'API Android Developer Console seguano questi pattern per garantire un'integrazione perfetta.

Stabilire 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, fornisci una spiegazione chiara della funzionalità prevista prima di avviare 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 del pacchetto per la verifica dello sviluppatore Android in [nome-applicazione]"
  • 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. Layout della finestra di dialogo del contesto di autorizzazione OAuth chiaro.

Identificare gli account sviluppatore

  1. Esegui l'integrazione con il metodo API ListDeveloperAccounts per recuperare ed elencare tutti gli account sviluppatore per i quali è stata autorizzata l'accesso.
  2. Fornisci un selettore di account per consentire allo sviluppatore di scegliere l'account sviluppatore che preferisce.
  3. Metti in evidenza il displayName dell'account, utilizzando il numero di conto bancario dal campo name come informazioni secondarie.
  4. Visualizza gli stati di verifica dell'account (verificationState):
    • VERIFIED: conferma l'identità dello sviluppatore verificata con un indicatore visivo positivo (ad es. un segno di spunta verde).
    • NOT_VERIFIED: indica che la verifica non è completa e limita la registrazione del pacchetto per l'account. Facoltativamente, fornisci un pulsante di invito all'azione principale che indirizza gli sviluppatori ad Android Developer Console dopo aver selezionato l'account.
Selettore account che mostra il nome dell'account sviluppatore e lo stato di verifica.
Figura 2. Selettore di account che mostra gli account sviluppatore e lo stato di verifica.

Se ricevi una risposta vuota perché non sono associati account sviluppatore all'Account Google, indirizza gli sviluppatori ad Android Developer Console utilizzando un pulsante di invito all'azione principale.

Gestire 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 efficacemente gli stati dei pacchetti.
  2. Visualizza il packageName insieme allo stato di registrazione corrente (DRAFT, IN_REVIEW, REGISTERED o PENDING_TRANSFER), applicando indicatori visivi distinti per ogni stato. Se è stato fornito e salvato un "nome descrittivo" durante la creazione, 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.

Gestire le chiavi

  1. Chiama l'endpoint API ListAndroidPackageKeys per recuperare tutte le chiavi collegate a un nome di pacchetto, offrendo agli sviluppatori una panoramica strutturata (ad esempio una tabella o un elenco) per monitorare lo stato di registrazione.
  2. Presenta il certificateFingerprintSha256 per ogni chiave insieme al relativo stato di registrazione (DRAFT, OWNERSHIP_VERIFIED, IN_REVIEW, REGISTERED_ACTIVE o PENDING_TRANSFER), utilizzando indicatori visivi distinti per differenziare gli stati.
Elenco delle impronte 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 integrando il metodo API CreateAndroidPackageKey.

Registrare un nome di pacchetto

  1. Utilizza un layout basato su moduli 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 es. tramite una richiesta precedente).
  2. Chiama il metodo API CreateAndroidPackage per registrare un nome di 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 (vedi Verificare la proprietà di una chiave di seguito).
    • Se keySelectionStrategy è impostato su USE_ANY_KEY: chiedi allo sviluppatore di fornire una chiave direttamente. In questo caso non è necessaria la verifica della proprietà della chiave.
  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 di pacchetto e la selezione di una chiave.

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

Verificare la proprietà di una chiave

Quando keySelectionStrategy è impostato su SELECT_KEY_FROM_LIST, gli sviluppatori devono dimostrare la proprietà della chiave di firma privata. Per dimostrare la proprietà, è necessario inviare un APK firmato che includa il verificationToken generato dall'API.

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

  • Componente di visualizzazione del token: visualizza il verificationToken in modo ben visibile 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 indicano allo sviluppatore di inserire un file adi-registration.properties contenente il verificationToken nella cartella degli asset dell'app.
  • Dropzone per l'invio dell'APK: offri una dropzone dedicata per il caricamento dei file per ricevere l'APK firmato.
Dropzone e visualizzazione dei token per la verifica della proprietà delle chiavi.
Figura 6. Componenti dell'interfaccia utente per la verifica della proprietà della chiave con il caricamento dell'APK firmato.

Giustificare la registrazione di una chiave

Quando il campo justificationRequired di una chiave nota è impostato su REQUIRED, la registrazione della chiave insieme al nome del pacchetto richiede agli sviluppatori di fornire una motivazione aziendale completa.

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

Automatizzare 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 suo conto.

Gestendo automaticamente il processo di inclusione del token e caricamento dell'APK, la tua applicazione elimina questi passaggi manuali. Assicurati di informare gli sviluppatori che la verifica della proprietà della chiave viene gestita senza problemi dalla tua applicazione utilizzando la chiave archiviata nel tuo sistema.

Seguire 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 utilizzo delle 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 indicato come verifica dello sviluppatore Android. Rispetta l'utilizzo delle maiuscole e l'ortografia esatti in tutti i contesti.

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

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

Utilizzare l'invito all'azione "Accedi"

L'autenticazione OAuth 2.0 con Android Developer Console si basa su Google Identity Services. Per rimanere conforme alle linee guida per il branding di 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 proprio Account Google.

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

Quando integri il logo di Android Developer Console nell'interfaccia dell'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 di branding 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 sempre essere sottoposto a rendering con le proporzioni completamente vincolate. Non devi mai distorcere, allungare, inclinare, ritagliare, capovolgere o modificare i componenti del logo. Non modificare la tavolozza di colori ufficiale, scambiare i colori di primo piano o di sfondo o applicare ombreggiature, effetti di luce o sfumature decorative.
  • Restrizioni 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 all'interno del contesto del layout dell'applicazione per indicare esplicitamente un'integrazione attiva.

Risorse aggiuntive