Questa pagina è stata tradotta dall'API Cloud Translation.

Guida all'integrazione

André Cipriani Bandarra

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 utilizzi le Attività web attendibili, il progetto deve avere come target l'API 16 o versioni successive.

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. Ecco una breve descrizione di ciascun campo:

Nome:il nome che verrà utilizzato per la tua applicazione nell'Avvio app di 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.
Lingua: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 altre caselle di controllo, poiché non utilizzeremo le app istantanee o gli elementi AndroidX, e fai clic su Fine.

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

Per configurare la libreria Attività web attendibile nel progetto, devi modificare il file di compilazione dell'applicazione. Cerca la sezione Script Gradle in Project Navigator. Esistono due file denominati build.gradle, il che può creare un po' di confusione, ma le descrizioni tra parentesi aiutano a identificare quello corretto.

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

La libreria Attività web attendibili utilizza funzionalità di Java 8 e la prima modifica abilita 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'
}

Android Studio ti chiederà di sincronizzare di nuovo il progetto. Fai clic sul link 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 app, seguita da manifest e fai doppio clic su AndroidManifest.xml per aprire il file.

Poiché abbiamo chiesto ad Android Studio di non aggiungere attività al nostro progetto durante la sua creazione, il file manifest è vuoto e contiene solo il tag application.

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:

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

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 deve essere stabilita in entrambi i modi, collegando dall'app al sito web e dal sito web all'app.

Per scopi di debug, è possibile configurare l'app per la convalida del sito web e Chrome in modo da saltare la convalida del sito web per l'app.

Stabilire un'associazione dall'app al sito web

Apri il file delle risorse stringa app > res > values > strings.xml e aggiungi la dichiarazione 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

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 ABILITATA, quindi riavvia il browser.
Successivamente, nell'applicazione Terminal del tuo sistema operativo, utilizza Android Debug Bridge (installato con Android Studio) ed esegui il seguente 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 dovrebbe ora essere visualizzata a schermo intero.

Stabilire un'associazione dal sito web all'app

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

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.

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 nell'avvio 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

Una volta inserito il file assetlinks nel tuo dominio e configurato il tag asset_statements 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, è possibile controllare la presenza di 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

Una volta generato l'APK di caricamento, puoi caricare l'app sul Play Store.

Aggiungere una schermata iniziale

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

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 dedurre 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/

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>

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 prima della schermata iniziale venga visualizzata una schermata bianca 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.