Guida all'integrazione

André Cipriani Bandarra

Twitter GitHub Glitch Mastodon Homepage

Nota: Nota: è ora disponibile una guida rapida più semplice alle attività web attendibili.

L'impostazione di un'attività web attendibile non richiede agli sviluppatori di creare codice Java, al contrario di Android Studio. Questa guida è stata creata utilizzando Android Studio 3.3. Consulta la documentazione su come installarlo.

Crea un progetto di attività web attendibile

Quando utilizzi attività web attendibili, il progetto deve avere come target l'API 16 o versioni successive.

Nota: questa sezione ti guiderà nella configurazione di un nuovo progetto su Android Studio. Se hai già familiarità con lo strumento, puoi passare direttamente alla sezione Recupero della Raccolta di attività web attendibile.

Apri Android Studio e fai clic su Avvia un nuovo progetto Android Studio.

Android Studio ti chiederà di scegliere un tipo di attività. Poiché le attività web attendibili utilizzano un'attività fornita dalla libreria dell'assistenza, scegli Aggiungi nessuna attività e fai clic su Avanti.

Nel passaggio successivo, la procedura guidata richiederà le configurazioni per il progetto. Ecco una breve descrizione di ogni campo:

• Nome: il nome che verrà utilizzato per la tua applicazione in Avvio app Android.
• Nome del pacchetto: un identificatore univoco per le app Android sul Play Store e sui dispositivi Android. Consulta la documentazione per ulteriori informazioni sui requisiti e le best practice per la creazione dei nomi dei pacchetti per le app per Android.
• Posizione di salvataggio: il percorso in cui Android Studio creerà il progetto nel file system.
• Linguaggio: il progetto non richiede la scrittura di codice Java o Kotlin. Seleziona Java come impostazione predefinita.
• Livello API minimo: la libreria di supporto richiede almeno il livello API 16. Seleziona l'API 16 qualsiasi versione sopra indicata.

Lascia deselezionate le restanti caselle di controllo, poiché non utilizzeremo app istantanee o gli artefatti AndroidX, e fai clic su Fine.

Scaricare la libreria di supporto di attività web attendibile

Per configurare la libreria di attività web attendibili nel progetto, devi modificare il file di build dell'applicazione. Cerca la sezione Script Gradle nel Navigatore di progetto. Esistono due file chiamati build.gradle, che potrebbero generare un po' di confusione e le descrizioni tra parentesi aiutano a identificare il file corretto.

Il file che stiamo cercando è quello con il nome del modulo Modulo.

La libreria Attività web attendibili utilizza le funzionalità di Java 8 e la prima modifica abilita Java 8. Aggiungi una sezione compileOptions alla parte inferiore della sezione android, come indicato di seguito:

android {
        ...
    compileOptions {
       sourceCompatibility JavaVersion.VERSION_1_8
       targetCompatibility JavaVersion.VERSION_1_8
    }
}

Nel passaggio successivo verrà aggiunta al progetto la libreria di supporto di attività web attendibile. Aggiungi una nuova dipendenza alla sezione dependencies:

dependencies {
    implementation 'com.google.androidbrowserhelper:androidbrowserhelper:2.2.0'
}

Android Studio mostrerà un messaggio che chiede di sincronizzare nuovamente il progetto. Fai clic sul link Sync Now (Sincronizza ora) e sincronizzalo.

Avvia l'attività web attendibile

Puoi configurare l'attività web attendibile modificando il file manifest delle app Android.

Nel Navigatore di progetto, espandi la sezione app, quindi i manifest e fai doppio clic su AndroidManifest.xml per aprire il file.

Poiché abbiamo chiesto ad Android Studio di non aggiungere attività al progetto al momento della creazione, il file manifest è vuoto e contiene solo il tag dell'applicazione.

Aggiungi l'Attività web attendibile inserendo un tag activity nel tag application:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:tools="http://schemas.android.com/tools"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme"
        tools:ignore="GoogleAppIndexingWarning">
        <activity
            android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">

           <!-- Edit android:value to change the url opened by the Trusted Web Activity -->
           <meta-data
               android:name="android.support.customtabs.trusted.DEFAULT_URL"
               android:value="https://airhorner.com" />

           <!-- This intent-filter adds the Trusted Web Activity to the Android Launcher -->
           <intent-filter>
               <action android:name="android.intent.action.MAIN" />
               <category android:name="android.intent.category.LAUNCHER" />
           </intent-filter>

           <!--
             This intent-filter allows the Trusted Web Activity to handle Intents to open
             airhorner.com.
           -->
           <intent-filter>
               <action android:name="android.intent.action.VIEW"/>
               <category android:name="android.intent.category.DEFAULT" />
               <category android:name="android.intent.category.BROWSABLE"/>

               <!-- Edit android:host to handle links to the target URL-->
               <data
                 android:scheme="https"
                 android:host="airhorner.com"/>
           </intent-filter>
        </activity>
    </application>
</manifest>

I tag aggiunti al file XML sono standard Android App Manifest. Esistono due informazioni rilevanti per il contesto delle attività web attendibili:

1. Il tag meta-data indica all'Attività web attendibile quale URL deve aprire. Modifica l'attributo android:value con l'URL della PWA che vuoi aprire. In questo esempio, è https://airhorner.com.
2. Il secondo tag intent-filter consente all'attività web attendibile di intercettare gli intent Android che aprono https://airhorner.com. L'attributo android:host all'interno del tag data deve indirizzare al dominio aperto dall'attività web attendibile.

Nota: quando esegui il progetto in questa fase, la barra degli URL delle schede personalizzate continuerà a essere visualizzata nella parte superiore dello schermo. Questo non è un bug.

La prossima sezione mostrerà come configurare Digital AssetLinks per verificare la relazione tra il sito web e l'app e come rimuovere la barra degli URL.

Rimuovere la barra degli URL

Le attività web attendibili richiedono un'associazione tra l'app Android e il sito web per rimuovere la barra degli URL.

Questa associazione viene creata tramite Digital Asset Links e deve essere stabilita in entrambi i modi, collegando dall'app al sito web e dal sito web all'app.

Puoi configurare la convalida dall'app al sito web e configurare Chrome in modo che ignori il sito web alla convalida dell'app a scopo di debug.

Creare un'associazione dall'app al sito web

Apri il file delle risorse stringa app > res > values > strings.xml e aggiungi l'istruzione Digital AssetLinks di seguito:

<resources>
    <string name="app_name">AirHorner Trusted Web Activity</string>
    <string name="asset_statements">
        [{
            \"relation\": [\"delegate_permission/common.handle_all_urls\"],
            \"target\": {
                \"namespace\": \"web\",
                \"site\": \"https://airhorner.com\"}
        }]
    </string>
</resources>

Modifica i contenuti dell'attributo site in modo che corrispondano allo schema e al dominio aperti dall'attività web attendibile.

Torna al file manifest dell'app Android, AndroidManifest.xml, per collegarti all'istruzione aggiungendo un nuovo tag meta-data, ma questa volta come elemento secondario del tag application:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.twa.myapplication">

    <application
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/AppTheme">

        <meta-data
            android:name="asset_statements"
            android:resource="@string/asset_statements" />

        <activity>
            ...
        </activity>

    </application>
</manifest>

Abbiamo stabilito una relazione tra l'applicazione Android e il sito web. È utile eseguire il debug di questa parte della relazione senza creare la convalida del sito web per l'applicazione.

Per eseguire un test su un dispositivo di sviluppo, procedi nel seguente modo:

Attivare la modalità di debug

1. Apri Chrome sul dispositivo di sviluppo, vai a chrome://flags, cerca un elemento denominato Attiva riga di comando su dispositivi non rooted e impostalo su ABILITATO, quindi riavvia il browser.
2. Quindi, nell'applicazione Terminale del tuo sistema operativo, utilizza Android Debug Bridge (installato con Android Studio) ed esegui questo comando:

adb shell "echo '_ --disable-digital-asset-link-verification-for-url=\"https://airhorner.com\"' > /data/local/tmp/chrome-command-line"

Chiudi Chrome e riavvia l'applicazione da Android Studio. L'applicazione ora dovrebbe essere visualizzata a schermo intero.

Nota: potrebbe essere necessario forzare la chiusura di Chrome, in modo che si riavvii con la riga di comando corretta. Vai a Impostazioni Android > App e notifiche > Chrome e fai clic su Forza interruzione.

Stabilire un'associazione dal sito web all'app

Per creare l'associazione, lo sviluppatore deve raccogliere dall'app due informazioni:

• Nome pacchetto: le prime informazioni sono il nome del pacchetto dell'app. Si tratta dello stesso nome di pacchetto generato durante la creazione dell'app. Lo puoi trovare anche all'interno del Modulo build.gradle, in Gradle Script > build.gradle (Module: app), ed è il valore dell'attributo applicationId.
• Impronta SHA-256: le app Android devono essere firmate per poter essere caricate sul Play Store. La stessa firma viene utilizzata per stabilire la connessione tra il sito web e l'app tramite l'impronta SHA-256 della chiave di caricamento.

La documentazione di Android spiega nel dettaglio come generare una chiave utilizzando Android Studio. Prendi nota del percorso, dell'alias e delle password dell'archivio chiavi, poiché ti serviranno nel passaggio successivo.

Estrai l'impronta SHA-256 utilizzando keytool, con il seguente comando:

keytool -list -v -keystore [path] -alias [alias] -storepass [password] -keypass [password]

Il valore dell'impronta SHA-256 viene stampato nella sezione delle impronte digitali del certificato. Ecco un output di esempio:

keytool -list -v -keystore ./mykeystore.ks -alias test -storepass password -keypass password

Alias name: key0
Creation date: 28 Jan 2019
Entry type: PrivateKeyEntry
Certificate chain length: 1
Certificate[1]:
Owner: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Issuer: CN=Test Test, OU=Test, O=Test, L=London, ST=London, C=GB
Serial number: ea67d3d
Valid from: Mon Jan 28 14:58:00 GMT 2019 until: Fri Jan 22 14:58:00 GMT 2044
Certificate fingerprints:
   SHA1: 38:03:D6:95:91:7C:9C:EE:4A:A0:58:43:A7:43:A5:D2:76:52:EF:9B
   SHA256: F5:08:9F:8A:D4:C8:4A:15:6D:0A:B1:3F:61:96:BE:C7:87:8C:DE:05:59:92:B2:A3:2D:05:05:A5:62:A5:2F:34
Signature algorithm name: SHA256withRSA
Subject Public Key Algorithm: 2048-bit RSA key
Version: 3

Con entrambe le informazioni a portata di mano, accedi al generatore di assetlinks, compila i campi e fai clic su Genera istruzione. Copia l'istruzione generata e pubblicala dal tuo dominio, dall'URL /.well-known/assetlinks.json.

Nota: il file AssetLinks deve essere in /.well-known/assetlinks.json, nella directory principale del dominio, in quanto è solo il punto in cui Chrome lo cercherà.

Creazione di un'icona

Quando Android Studio crea un nuovo progetto, questo viene fornito con un'icona predefinita. In qualità di sviluppatore, devi creare una tua icona e differenziare la tua applicazione dalle altre in Avvio app di Android.

Android Studio contiene Image Asset Studio, che fornisce gli strumenti necessari per creare le icone corrette, per ogni risoluzione e per plasmare le esigenze della tua applicazione.

In Android Studio, vai a File > New > Image Asset, seleziona Launcher Icons (Adaptative and Legacy) e segui i passaggi della procedura guidata per creare un'icona personalizzata per l'applicazione.

Generazione di un APK firmato in corso...

Con il file assetlinks nel tuo dominio e il tag asset_statements configurato nell'applicazione Android, il passaggio successivo consiste nel generare un'app firmata. Anche in questo caso, la procedura è ampiamente documentata.

L'APK di output può essere installato su un dispositivo di test utilizzando adb:

adb install app-release.apk

Se il passaggio della verifica non va a buon fine, è possibile verificare la presenza di messaggi di errore utilizzando Android Debug Bridge, dal terminale del sistema operativo e con il dispositivo di test collegato.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Dopo aver generato l'APK di caricamento, ora puoi caricare l'app sul Play Store.

Aggiunta di una schermata iniziale

A partire da Chrome 75, le attività web attendibili supportano le schermate iniziali. La schermata iniziale può essere impostata aggiungendo alcuni nuovi file immagine e configurazioni al progetto.

Assicurati di eseguire l'aggiornamento a Chrome 75 o versioni successive e di utilizzare la versione più recente della libreria di supporto di attività web attendibili.

Generazione delle immagini per la schermata iniziale

I dispositivi Android possono avere dimensioni dello schermo e densità di pixel diverse. Per assicurarti che la schermata iniziale venga visualizzata correttamente su tutti i dispositivi, devi generare l'immagine per ogni densità di pixel.

Una spiegazione completa dei pixel indipendenti dalla visualizzazione (dp o dip) non rientra nell'ambito di questo articolo, ma un esempio è la creazione di un'immagine di 320 x 320 dp, ovvero un quadrato di 2 x 2 pollici sullo schermo di un dispositivo di qualsiasi densità e equivalente a 320 x 320 pixel alla densità di mdpi.

Da qui possiamo ricavare le dimensioni necessarie per altre densità di pixel. Di seguito è riportato un elenco con le densità dei pixel, il moltiplicatore applicato alle dimensioni della base (320 x 320 dp), le dimensioni risultanti in pixel e la posizione in cui l'immagine deve essere aggiunta nel progetto Android Studio.

Densità	Moltiplicatore	Dimensioni	Località progetto
mdpi (base di riferimento)	1x	320x320 px	/res/drawable-mdpi/
ldpi	0,75x	240x240 px	/res/drawable-ldpi/
hdpi	1,5x	480x480 px	/res/drawable-hdpi/
xhdpi	2x	640x640 px	/res/drawable-xhdpi/
XXhdpi	3,0x	960x960 px	/res/drawable-xxhdpi/
xxxhdpi	4,0x	1280x1280 px	/res/drawable-xxxhdpi/

Nota: un'alternativa alla creazione di tutte le dimensioni delle immagini è utilizzare un solo disegno vettoriale. Vector Asset Studio offre strumenti per aiutare gli sviluppatori a trasformare i file SVG in Vector Drawables Android.

Aggiornamento dell'applicazione

Dopo aver generato le immagini per la schermata iniziale, è il momento di aggiungere le configurazioni necessarie al progetto.

Innanzitutto, aggiungi un provider di contenuti al file manifest Android (AndroidManifest.xml).

<application>
    ...
    <provider
        android:name="androidx.core.content.FileProvider"
        android:authorities="com.example.twa.myapplication.fileprovider"
        android:grantUriPermissions="true"
        android:exported="false">
        <meta-data
            android:name="android.support.FILE_PROVIDER_PATHS"
            android:resource="@xml/filepaths" />
    </provider>
</application>

Nota: assicurati di modificare l'attributo android:authorities quando crei il provider, poiché due applicazioni non possono avere la stessa autorità su un dispositivo.

Quindi, aggiungi la risorsa res/xml/filepaths.xml e specifica il percorso della schermata iniziale di twa:

<paths>
    <files-path path="twa_splash/" name="twa_splash" />
</paths>

Infine, aggiungi meta-tags al file manifest Android per personalizzare LauncherActivity:

<activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity">
    ...
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_IMAGE_DRAWABLE"
               android:resource="@drawable/splash"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_BACKGROUND_COLOR"
               android:resource="@color/colorPrimary"/>
    <meta-data android:name="android.support.customtabs.trusted.SPLASH_SCREEN_FADE_OUT_DURATION"
               android:value="300"/>
    <meta-data android:name="android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY"
               android:value="com.example.twa.myapplication.fileprovider"/>
    ...
</activity>

Assicurati che il valore del tag android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY corrisponda al valore definito dell'attributo android:authorities all'interno del tag provider.

Rendere trasparente LauncherActivity

Inoltre, assicurati che LauncherActivity sia trasparente per evitare che venga visualizzata una schermata bianca prima della schermata iniziale impostando un tema traslucido per LauncherActivity:

<application>
    ...
    <activity android:name="com.google.androidbrowserhelper.trusted.LauncherActivity"
              android:theme="@android:style/Theme.Translucent.NoTitleBar">
    ...
    </activity>
</application>

Non vediamo l'ora di scoprire cosa creano gli sviluppatori con le attività web attendibili. Per lasciare un feedback, contattaci all'indirizzo @ChromiumDev.