Concetti di Android (per sviluppatori web)

Peter Conn
Peter Conn
X GitHub
Joyce Toh
Joyce Toh
GitHub

Se sei uno sviluppatore web che non ha mai utilizzato Android e Google Play, dovresti conoscere alcuni dettagli. Esistono già molte risorse e documentazione al riguardo (grazie al team Android), ma qui evidenzieremo alcuni concetti importanti e il loro rapporto con Bubblewrap.

Chiave di caricamento e chiave di firma

Se prevedi di utilizzare il wrapping di app per generare un Android App Bundle (AAB) (nota: a partire da agosto 2021, Google Play richiederà che tutte le nuove app utilizzino il formato Android App Bundle) o l'APK da caricare e pubblicare su Google Play, dovrai firmare la tua app con una chiave di firma. Google Play ti offre due opzioni per gestire questa situazione:

  • Firma dell'app di Google Play (vivamente consigliata): Google gestirà e proteggerà per te la chiave di firma della tua app. e lo utilizza per firmare gli APK per la distribuzione. La firma dell'app di Google Play utilizza due chiavi. La "chiave di firma dell'app" che verrà gestita da Google per te e la "chiave di caricamento" che conservi e che dovrebbe rimanere privata. Utilizzerai la chiave di caricamento per firmare l'app e caricarla su Play Console. Questo sistema ti permette di reimpostare la chiave di caricamento in caso di smarrimento o compromissione contattando il team di assistenza di Google Play. Al momento, Google Play ti consente di caricare la tua app come AAB o APK:
    • Android App Bundle (AAB): quando carichi un AAB su Play Console, la creazione e la generazione degli APK sono rinviate al Google Play Store. Quando un utente scarica e installa la tua app, Google Play la distribuirà come APK firmato. Di conseguenza, la firma degli APK dovrà quindi essere effettuata anche da Google Play. Quindi, per impostazione predefinita, se carichi la tua app come AAB su Play Console, dovrai utilizzare la firma dell'app di Google Play.
    • APK. Con gli APK puoi scegliere di attivare la firma dell'app di Google Play. Ti consigliamo vivamente di attivare la firma dell'app di Google Play perché aumenta la sicurezza della tua chiave di firma. Come indicato in precedenza, a breve Google Play richiederà che tutte le nuove app vengano caricate in formato AAB, quindi ti consigliamo di farlo anziché caricare APK.
  • Gestisci la tua chiave di firma: se scegli di gestire la tua chiave e non attivi la funzionalità di firma dell'app di Google Play, sei pienamente responsabile della chiave di firma della tua app. A differenza della firma dell'app di Google Play, non è possibile reimpostarla se perdi la chiave. Di conseguenza, se perdi la chiave di firma dell'app perderai anche la possibilità di aggiornare l'app.

Durante la configurazione di bubblewrap init, quando arrivi alla sezione "Informazioni sulla chiave di firma (5/5)", ti verrà chiesto di inserire "Posizione negozio chiave" e "Nome chiave" oppure di utilizzare i valori predefiniti. Il percorso predefinito dell'archivio chiavi è il file android.keystore nella directory del progetto, mentre il nome della chiave predefinito è android. Se il wrapping di parole non trova un archivio chiavi esistente con quel nome nella posizione, ne creerà uno per te e ti chiederà anche le password. Prendi nota delle password che hai inserito perché ti serviranno durante il processo di creazione (bubblewrap build), in cui verranno utilizzate la chiave per firmare l'app. Se attivi la firma dell'app di Google Play, la chiave di firma generata e utilizzata per firmare la tua app diventa la "chiave di caricamento". Indipendentemente dal fatto che tu scelga di utilizzare la chiave generata con wrapping come chiave di firma o di caricamento, devi proteggere e mantenere privata la chiave. Sconsigliamo di eseguirne il commit nel controllo della versione. Limita invece il numero di persone che possono accedervi.

Sono necessari i link ad asset digitali per dichiarare la relazione tra il tuo sito web e la tua app per Android. Per assicurarti che l'app per Android generata da Bubblewrap sia verificata correttamente e venga avviata come attività web attendibile (anziché una scheda personalizzata di Chrome), devi aggiungere la chiave appropriata al file assetlinks.json. Poi caricalo sul tuo sito web all'indirizzo .well-known/assetlinks.json (relativo al dominio principale). Il tuo file assetlinks.json deve avere questo formato:

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

Recuperare l'impronta digitale del certificato SHA256

Per creare il file assetlinks.json, devi avere l'impronta digitale del certificato SHA 256 associata alla chiave di firma dell'app. La cosa importante da notare è che le fingerprint associate alle chiavi di firma e di caricamento saranno diverse. È importante tenere a mente questa distinzione, soprattutto se noti che l'app viene avviata come scheda personalizzata di Chrome (con la barra del browser visibile). Quindi, è probabile che il tuo file assetlinks.json non abbia l'impronta corrispondente alla chiave appropriata.

È utile inserire l'impronta del certificato di firma e di caricamento in assetlinks.json per eseguire più facilmente il debug della tua app in locale. Consulta la sezione Aggiungere altre chiavi di seguito per ulteriori informazioni su come avere entrambe le chiavi nel file assetlinks.json.

Esistono un paio di modi per recuperare l'impronta, descritti nelle sezioni successive. Dovrebbero fornirti tutte le stesse impronte, quindi scegli pure il metodo più comodo.

Tramite Play Console

A seconda che tu abbia attivato o meno la firma dell'app di Google Play, potresti avere uno o due chiavi. Per recuperare l'impronta SHA256 appropriata per ogni chiave:

  1. Vai a Play Console.
  2. Seleziona l'app che ti interessa
  3. Nel menu di navigazione a sinistra, in Release, vai a Configurazione -> Integrità dell'app.
  4. Copia il valore SHA256 per la chiave appropriata:

Recupera l'impronta digitale del certificato SHA256 appropriata per la chiave di firma o di caricamento

  • Chiave di firma: copia l'impronta SHA256 per il "certificato della chiave di firma dell'app". Questa impronta corrisponderà alla tua app se la scarichi dal Google Play Store, poiché Google Play distribuisce la tua app firmata con la chiave di firma.

  • Chiave di caricamento: copia l'impronta SHA256 in "Upload key certificate" (Certificato della chiave di caricamento). Questa impronta corrisponderà alla tua app se la installi in locale (ad esempio tramite ADB tramite USB). L'APK (sulla tua macchina locale) è stato creato da Bubblewrap e, pertanto, è firmato anche dalla chiave che ha creato per te (durante la configurazione di init). Ricorda che potrebbe essere la chiave di firma dell'app installata in locale, ma che in realtà diventa la "chiave di caricamento" una volta pubblicata l'app tramite Google Play.

Via keytool

keytool è uno strumento di gestione di chiavi e certificati. Puoi utilizzare keytool per estrarre l'impronta SHA 256 associata all'APK o al Bubblewrap AAB generato. Tieni presente che questa impronta è destinata alla chiave di firma locale e, se carichi la tua app su Google Play e attivi la firma dell'app di Google Play, questa chiave diventa la "chiave di caricamento". 

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

Un altro modo per ottenere il file Digital Asset Links corretto per la tua app è utilizzare lo strumento Asset Link:

  1. Installa lo strumento Asset Link dal Play Store.
  2. Sullo stesso dispositivo, scarica la tua app dal Google Play Store o installala localmente.
  3. Apri l'app Asset Link Tool e ti verrà fornito un elenco di tutte le applicazioni installate sul tuo dispositivo in base al nome del pacchetto. Filtra l'elenco in base all'ID applicazione che hai scelto in precedenza durante bubblewrap init e fai clic sulla voce.
  4. Vedrai una pagina con la firma della tua app e un link agli asset digitali generato. Fai clic sui pulsanti Copia o Condividi in basso per esportarlo come preferisci (ad esempio, salva in Google Keep, invia a te stesso un'email).

Lo stesso vale per le chiavi di firma o di caricamento. Se hai installato la tua app dal Google Play Store, lo strumento Asset Link ti fornirà l'impronta per la chiave di firma dell'app. Se hai installato l'app direttamente dalla tua macchina locale, l'impronta digitale verrà utilizzata per il wrapping di parole chiave generato.

Ora che lo hai caricato, assicurati di poter accedere al file dei link degli asset in un browser. Verifica che https://example.com/.well-known/assetlinks.json venga risolto nel file appena caricato.

Siti web basati su Jekyll

Se il tuo sito web è stato generato da Jekyll (ad esempio con le Pagine GitHub), dovrai aggiungere una riga di configurazione in modo che la directory .well-known sia inclusa nell'output. Nella guida di GitHub puoi trovare ulteriori informazioni su questo argomento. Crea un file denominato _config.yml nella directory principale del tuo sito (oppure aggiungilo se esiste già) e inserisci:

# Folders with dotfiles are ignored by default.
include: [.well-known]

Aggiunta di altre chiavi

Un file Digital Asset Link può contenere più di un'app e più di una chiave per ogni app. Ad esempio, per aggiungere una seconda chiave, utilizza lo strumento Link asset per determinarla e aggiungerla come seconda voce. Il codice in Chrome che analizza questo JSON è piuttosto rigoroso, quindi assicurati di non aggiungere per sbaglio una virgola in più alla fine dell'elenco.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

Risoluzione dei problemi

Chrome registra il motivo per cui la verifica di Digital Asset Links non va a buon fine e puoi visualizzare i log su un dispositivo Android con adb logcat. Se stai sviluppando su Linux/Mac, puoi visualizzare i log pertinenti di un dispositivo connesso con:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

Ad esempio, se visualizzi il messaggio Statement failure matching fingerprint., devi utilizzare lo strumento Link asset per vedere la firma della tua app e assicurarti che corrisponda a quella nel file assetlinks.json.