Questa pagina è stata tradotta dall'API Cloud Translation.

Concetti di Android (per sviluppatori web)

Peter Conn

Joyce Toh

Se sei uno sviluppatore web alle prime armi con Android e Google Play, ci sono alcuni dettagli che devi conoscere. Esistono già molte risorse e documentazione in merito (grazie al team di Android), ma qui evidenzieremo alcuni concetti importanti e il loro rapporto con Bubblewrap.

Chiave di caricamento e chiave di firma

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

Firma dell'app di Google Play (opzione vivamente consigliata): Google gestirà e proteggerà automaticamente la chiave di firma della tua app. che la utilizza per firmare gli APK da distribuire. La funzionalità di firma dell'app di Google Play utilizza due chiavi. La "chiave di firma dell'app" che verrà gestita da Google e la "chiave di caricamento" che dovrai conservare e che deve rimanere privata. La chiave di caricamento viene utilizzata per firmare l'app da caricare su Play Console. Questo sistema ti consente di reimpostare la chiave di caricamento se viene smarrita o compromessa contattando il team di assistenza di Google Play. Al momento, Google Play consente di caricare l'app come AAB o APK:
- Android App Bundle (AAB): quando carichi un AAB su Play Console, rimandi la compilazione e la generazione degli APK al Google Play Store. Quando un utente scarica e installa la tua app, Google Play la distribuisce come APK firmato. Pertanto, la firma degli APK dovrà essere eseguita anche da Google Play. Pertanto, per impostazione predefinita, se carichi la tua app come AAB su Play Console, ti verrà richiesto di utilizzare la firma dell'app Google Play.
- APK: con gli APK, hai la possibilità di attivare la funzionalità Firma dell'app di Google Play. Ti consigliamo vivamente di attivare la funzionalità Firma dell'app di Google Play perché aumenta la sicurezza della chiave di firma. Come indicato in precedenza, a breve Google Play richiederà che tutte le nuove app vengano caricate nel formato AAB, pertanto consigliamo di procedere in questo modo anziché caricare gli APK.
Gestisci la tua chiave di firma: se scegli di gestire la tua chiave e di non attivare la funzionalità Firma dell'app di Google Play, sei pienamente responsabile della chiave di firma della tua app. A differenza di quanto accade con la firma dell'app di Google Play, non è possibile reimpostarla se perdi la chiave. Pertanto, se perdi la chiave di firma dell'app, perdi anche la possibilità di aggiornarla.

Durante la configurazione di bubblewrap init, quando arrivi alla sezione "Informazioni sulla chiave di firma (5/5)", ti verrà chiesto di inserire una "Posizione del magazzino chiavi" e un "Nome della chiave" oppure di utilizzare i valori predefiniti. La posizione predefinita del magazzino delle chiavi è il file android.keystore nella directory del progetto e il nome della chiave predefinito è android. Se Bubblewrap non trova un archivio chiavi esistente con il nome della chiave nella directory, ne crea uno e ti chiede anche le password. Prendi nota delle password inserite, poiché ti serviranno durante il processo di compilazione (bubblewrap build), in cui verrà utilizzata la chiave per firmare l'app. Se attivi la funzionalità di firma dell'app di Google Play, la chiave di firma generata e utilizzata da Bubblewrap per firmare l'app diventa la "chiave di caricamento". Indipendentemente dal fatto che tu scelga di utilizzare la chiave generata da Bubblewrap come chiave di firma o di caricamento, devi proteggerla e mantenerla privata. Sconsigliamo di eseguire il commit nel controllo versione. Limita invece il numero di persone che possono accedervi.

Digital Asset Links

I link agli asset digitali sono necessari per dichiarare la relazione tra il tuo sito web e la tua app Android. Per assicurarti che l'app per Android generata da Bubblewrap venga verificata correttamente e venga avviata come attività web attendibile (anziché come scheda personalizzata di Chrome), devi aggiungere la chiave appropriata al file assetlinks.json. Caricalo sul tuo sito web all'indirizzo .well-known/assetlinks.json (rispetto alla directory principale). Il file assetlinks.json deve avere il seguente formato:

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

Ottenere l'impronta digitale del certificato SHA256

Per creare il file assetlinks.json, ti servirà l'impronta digitale del certificato SHA 256 associata alla chiave di firma della tua app. È importante notare che le impronte associate alle chiavi di firma e di caricamento saranno diverse. È importante tenere presente questa distinzione, soprattutto se noti che l'app si avvia come scheda personalizzata di Chrome (con la barra del browser visibile). In questo caso, è probabile che il file assetlinks.json non contenga la impronta corrispondente alla chiave appropriata.

È utile avere sia l'impronta del certificato di firma sia quella del certificato di caricamento in assetlinks.json per eseguire più facilmente il debug dell'app localmente. Consulta la sezione Aggiunta di altre chiavi di seguito per ulteriori informazioni su come avere entrambe le chiavi nel file assetlinks.json.

Esistono diversi modi per ottenere l'impronta, descritti nelle sezioni successive. Dovrebbero darti tutte le stesse impronte, quindi scegli il metodo più pratico.

Tramite Play Console

A seconda che tu attivi o meno la funzionalità Firma dell'app di Google Play, potresti avere una o due chiavi. Per recuperare l'impronta SHA256 appropriata per ogni chiave:

Vai a Play Console
Seleziona l'app che ti interessa
Nel menu di navigazione a sinistra, in Release, vai a Configurazione -> Integrità dell'app.
Copia l'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". Questo 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 per il "Certificato chiave di caricamento". Questo fingerprinting corrisponderà alla tua app se la installi localmente (ad esempio tramite ADB tramite USB). L'APK (sul tuo computer locale) è stato creato da Bubblewrap e, pertanto, firmato anche dalla chiave che ha creato per te (durante la configurazione di init). Tieni presente che questa potrebbe essere la chiave di firma per l'app installata localmente, ma diventa effettivamente la "chiave di caricamento" quando pubblichi l'app tramite Google Play.

Via `keytool`

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

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

Tramite lo strumento di collegamento delle risorse

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

Installa lo strumento Asset Link dal Play Store.
Sullo stesso dispositivo, scarica l'app dal Google Play Store o installala localmente.
Apri l'app Asset Link Tool e visualizzerai 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.
Viene visualizzata una pagina che elenca la firma dell'app e un link a un asset digitale generato. Fai clic sui pulsanti Copia o Condividi in basso per esportarlo come preferisci (ad es. salvarlo in Google Keep o inviarlo a te stesso via email).

Lo stesso vale per le chiavi di firma o di caricamento. Se hai installato l'app dal Google Play Store, lo strumento Asset Link ti fornirà l'impronta della chiave di firma dell'app. Se hai installato l'app direttamente dalla tua macchina locale, l'impronta è per la chiave generata da Bubblewrap.

Assicurarsi che il file del link agli asset sia accessibile

Ora che lo hai caricato, assicurati di poter accedere al file del link agli asset in un browser. Verifica che https://example.com/.well-known/assetlinks.json rimandi al file che hai appena caricato.

Siti web basati su Jekyll

Se il tuo sito web viene generato da Jekyll (ad esempio GitHub Pages), devi aggiungere una riga di configurazione in modo che la directory .well-known sia inclusa nell'output. La guida di GitHub contiene ulteriori informazioni su questo argomento. Crea un file denominato _config.yml nella directory principale del tuo sito (o 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 per ogni app può contenere più di una chiave. Ad esempio, per aggiungere una seconda chiave, utilizza lo strumento di collegamento degli asset per determinare la chiave e aggiungerla come seconda voce. Il codice in Chrome che analizza questo JSON è piuttosto rigoroso, quindi assicurati di non aggiungere accidentalmente un'altra virgola 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 della mancata verifica di Digital Asset Links e puoi visualizzare i log su un dispositivo Android con adb logcat. Se esegui lo sviluppo su Linux/Mac, puoi visualizzare i log pertinenti da 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 Asset Link per visualizzare la firma della tua app e assicurarti che corrisponda a quella nel file assetlinks.json.