Guida all'integrazione

André Cipriani Bandarra

Nota: è ora disponibile una guida rapida più semplice per le Attività web attendibili.

La configurazione di un'Attività web attendibile non richiede agli sviluppatori di scrivere codice Java, ma è obbligatoria l'installazione di Android Studio. Questa guida è stata creata utilizzando Android Studio 3.3. Consulta la documentazione su come installarlo.

Creare un progetto Attività web attendibile

Quando si utilizzano 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 conosci già lo strumento, puoi passare alla sezione Ottenere la raccolta di attività web attendibili.

Apri Android Studio e fai clic su Crea 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 di supporto, scegli Aggiungi nessuna attività e fai clic su Avanti.

Nel passaggio successivo, la procedura guidata richiederà le configurazioni per il progetto. Di seguito è riportata una breve descrizione di ciascun campo:

• Nome: il nome che verrà utilizzato per la tua applicazione in Avvio app Android.
• Nome pacchetto:un identificatore univoco per le applicazioni Android sul Play Store e sui dispositivi Android. Consulta la documentazione per ulteriori informazioni sui requisiti e sulle best practice per la creazione dei nomi dei pacchetti per le app per Android.
• Posizione di salvataggio:la posizione 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 assistenza richiede almeno il livello API 16. Seleziona API 16 o una versione successiva.

Lascia deselezionate le caselle di controllo rimanenti, dato che non utilizzeremo le app istantanee o gli elementi di AndroidX, quindi fai clic su Fine.

Ottenere la libreria di assistenza per l'Attività web attendibile

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

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

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

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

Il passaggio successivo consiste nell'aggiungere la libreria di supporto per le attività web attendibili al progetto. Aggiungi una nuova dipendenza alla sezione dependencies:

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

In Android Studio verrà visualizzato un messaggio che chiede di sincronizzare ancora una volta il progetto. Fai clic sul link Sync Now (Sincronizza ora) e sincronizzalo.

Avvia l'Attività web attendibile

La configurazione dell'Attività web attendibile viene eseguita modificando il manifest dell'app per Android.

In Project Navigator, espandi la sezione dell'app, seguita dai manifest e fai doppio clic su AndroidManifest.xml per aprire il file.

Poiché abbiamo chiesto ad Android Studio di non aggiungere alcuna attività al nostro progetto durante la 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 pertinenti per il contesto delle attività web affidabili:

1. Il tag meta-data indica ad 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 puntare al dominio aperto dall'Attività web attendibile.

Nota: quando esegui il progetto in questa fase, la barra dell'URL delle schede personalizzate continuerà a essere visualizzata nella parte superiore dello schermo. Non si tratta di un bug.

Nella sezione successiva viene mostrato come configurare Digital AssetLink per verificare la relazione tra il sito web e l'app e rimuovere la barra degli URL.

Rimuovere la barra degli URL

Per rimuovere la barra degli URL, è necessario stabilire un'associazione tra l'applicazione Android e il sito web.

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

È possibile configurare l'app in modalità di convalida del sito web e configurare Chrome in modo da passare dal sito web alla convalida dell'app a fini di debug.

Stabilire un'associazione dall'app al sito web

Apri il file di risorse stringa app > res > values > strings.xml e aggiungi l'istruzione Digital AssetLinks riportata 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 nel file manifest dell'app Android, AndroidManifest.xml, e fai il link all'affermazione 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>

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

Ecco come eseguire il test su un dispositivo di sviluppo:

Abilita modalità di debug

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

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 dovrebbe ora essere visualizzata a schermo intero.

Nota: potrebbe essere necessario chiudere forzatamente Chrome in modo che 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

Lo sviluppatore deve raccogliere due informazioni dall'app per creare l'associazione:

• Nome del pacchetto: le prime informazioni sono il nome del pacchetto dell'app. Si tratta dello stesso nome del pacchetto generato durante la creazione dell'app. Lo puoi trovare anche all'interno del modulo build.gradle, in Script Gradle > build.gradle (modulo: app) ed è il valore dell'attributo applicationId.
• Impronta SHA-256:le applicazioni 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 in dettaglio come generare una chiave utilizzando Android Studio. Assicurati di annotare il percorso, l'alias e le password per il key store, poiché ti serviranno per il 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 è stampato nella sezione Impronte del certificato. Ecco un esempio di output:

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

Una volta che hai a disposizione entrambe le informazioni, vai al generatore di assetlink, compila i campi e fai clic su Genera dichiarazione. Copia l'istruzione generata e pubblicala dal tuo dominio, dall'URL /.well-known/assetlinks.json.

Nota: il file AssetLinks deve trovarsi in /.well-known/assetlinks.json, nella directory principale del dominio, poiché è l'unico posto in cui Chrome lo cercherà.

Creare un'icona

Quando Android Studio crea un nuovo progetto, viene fornito con un'icona predefinita. In qualità di sviluppatore, ti consigliamo di creare la tua icona e differenziare la tua applicazione dalle altre nel launcher di Android.

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

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

Generazione di un APK firmato

Con il file assetlinks nel tuo dominio e il tag asset_statements configurato nell'applicazione per Android, il passaggio successivo consiste nel generare un'app firmata. Anche in questo caso, i passaggi sono ampiamente documentati.

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

adb install app-release.apk

Se il passaggio di verifica non va a buon fine, puoi controllare i messaggi di errore utilizzando Android Debug Bridge, dal terminale del sistema operativo e con il dispositivo di test connesso.

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 per le 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 di benvenuto venga visualizzata correttamente su tutti i dispositivi, dovrai generare l'immagine per ogni densità di pixel.

Una spiegazione completa dei pixel indipendenti dal display (dp o dip) esula dall'ambito di questo articolo, ma un esempio potrebbe essere la creazione di un'immagine di 320 x 320 dp, che rappresenta un quadrato di 5 x 5 cm sullo schermo di un dispositivo di qualsiasi densità ed è equivalente a 320 x 320 pixel con una densità di mdpi.

Da qui possiamo ricavare le dimensioni necessarie per altre densità di pixel. Di seguito è riportato un elenco con le densità di pixel, il moltiplicatore applicato alle dimensioni di 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 (valore 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 Vector Drawable. Vector Asset Studio offre strumenti per aiutare gli sviluppatori a trasformare gli SVG in Android Vector Drawable.

Aggiornamento dell'applicazione

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

Innanzitutto, aggiungi un content-provider al file Android Manifest (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.

Aggiungi la risorsa res/xml/filepaths.xml e specifica il percorso della schermata di benvenuto del TWA:

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

Infine, aggiungi meta-tags ad Android Manifest 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 sia uguale 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 creeranno gli sviluppatori con le attività web attendibili. Per inviare un feedback, contattaci all'indirizzo @ChromiumDev.