Cette page a été traduite par l'API Cloud Translation.

Guide d'intégration

André Cipriani Bandarra

La configuration d'une activité Web sécurisée ne nécessite pas que les développeurs écrivent du code Java, mais Android Studio est obligatoire. Ce guide a été créé avec Android Studio 3.3. Consultez la documentation d'installation.

Créer un projet d'activité Web fiable

Lorsque vous utilisez des activités Web sécurisées, le projet doit cibler l'API 16 ou une version ultérieure.

Ouvrez Android Studio, puis cliquez sur Start a new Android Studio project (Démarrer un nouveau projet Android Studio).

Android Studio vous invite à choisir un type d'activité. Étant donné que les activités Web fiables utilisent une activité fournie par la bibliothèque d'assistance, sélectionnez Add No Activity (N'ajouter aucune activité) et cliquez sur Next (Suivant).

L'assistant vous invite ensuite à configurer le projet. Voici une brève description de chaque champ:

Name (Nom) : nom utilisé pour votre application dans le Lanceur d'applications Android.
Nom du package:identifiant unique des applications Android sur le Play Store et sur les appareils Android. Consultez la documentation pour en savoir plus sur les exigences et les bonnes pratiques concernant la création de noms de packages pour les applications Android.
Emplacement d'enregistrement:emplacement où Android Studio créera le projet dans le système de fichiers.
Langage:le projet ne nécessite aucun code Java ou Kotlin. Sélectionnez Java comme valeur par défaut.
Niveau d'API minimal:la bibliothèque d'assistance nécessite au moins le niveau d'API 16. Sélectionnez l'API 16 ou une version ultérieure.

Ne cochez pas les autres cases, car nous n'utiliserons pas d'applis instantanées ni d'artefacts AndroidX, puis cliquez sur Finish (Terminer).

Obtenir la bibliothèque d'assistance pour les activités Web fiables

Pour configurer la bibliothèque d'activités Web fiables dans le projet, vous devez modifier le fichier de compilation de l'application. Recherchez la section Scripts Gradle dans le Project Navigator (Navigateur de projets). Il existe deux fichiers appelés build.gradle, ce qui peut prêter à confusion. Les descriptions entre parenthèses permettent d'identifier le fichier approprié.

Le fichier que nous recherchons est celui dont le module Module est indiqué à côté de son nom.

La bibliothèque des activités Web sécurisées utilise des fonctionnalités Java 8, et la première modification active Java 8. Ajoutez une section compileOptions au bas de la section android, comme suit:

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

L'étape suivante consiste à ajouter la bibliothèque d'assistance pour les activités Web sécurisées au projet. Ajoutez une dépendance à la section dependencies:

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

Android Studio vous invite à synchroniser le projet une nouvelle fois. Cliquez sur le lien Sync Now (Synchroniser) et synchronisez-le.

Lancer l'activité Web fiable

Pour configurer l'activité Web fiable, modifiez le fichier manifeste d'application Android.

Dans le Project Navigator (Navigateur de projets), développez la section app (Application), puis les manifests (fichiers manifestes), puis double-cliquez sur AndroidManifest.xml pour ouvrir le fichier.

Étant donné que nous avons demandé à Android Studio de ne pas ajouter d'activité à notre projet lors de sa création, le fichier manifeste est vide et ne contient que le tag d'application.

Ajoutez l'activité Web sécurisée en insérant une balise activity dans la balise 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>

Les balises ajoutées au fichier XML sont des fichiers manifestes d'application Android standards. Deux informations sont pertinentes pour le contexte des activités Web fiables:

La balise meta-data indique à l'activité Web fiable l'URL qu'elle doit ouvrir. Remplacez l'attribut android:value par l'URL de la PWA que vous souhaitez ouvrir. Dans cet exemple, il s'agit de https://airhorner.com.
La deuxième balise intent-filter permet à l'activité Web fiable d'intercepter les intents Android qui ouvrent https://airhorner.com. L'attribut android:host dans la balise data doit pointer vers le domaine ouvert par l'activité Web fiable.

La section suivante explique comment configurer des Digital AssetLinks pour vérifier la relation entre le site Web et l'application, et supprimer la barre d'URL.

Supprimer la barre d'adresse

Pour supprimer la barre d'URL, les activités Web fiables nécessitent une association entre l'application Android et le site Web.

Cette association est créée via des Digital Asset Links. Elle doit être établie dans les deux sens, en associant l'application au site Web et le site Web à l'application.

Il est possible de configurer l'application pour la validation du site Web et de configurer Chrome pour ignorer la validation du site Web vers l'application, à des fins de débogage.

Établir une association entre l'application et le site Web

Ouvrez le fichier de ressources de chaîne app > res > values > strings.xml et ajoutez l'instruction Digital AssetLinks ci-dessous:

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

Modifiez le contenu de l'attribut site pour qu'il corresponde au schéma et au domaine ouverts par l'activité Web de confiance.

De retour dans le fichier manifeste d'application Android, AndroidManifest.xml, créez un lien vers l'instruction en ajoutant une balise meta-data, mais cette fois en tant qu'enfant de la balise 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>

Nous avons maintenant établi une relation entre l'application Android et le site Web. Il est utile de déboguer cette partie de la relation sans créer la validation du site Web vers l'application.

Pour tester cela sur un appareil de développement:

Activer le mode de débogage

Ouvrez Chrome sur l'appareil de développement, accédez à chrome://flags, recherchez l'élément Enable command line on non-rooted devices (Activer la ligne de commande sur les appareils non en mode root), puis définissez-le sur ENABLED (ACTIVE). Redémarrez ensuite le navigateur.
Ensuite, dans l'application Terminal de votre système d'exploitation, utilisez Android Debug Bridge (installé avec Android Studio) et exécutez la commande suivante:

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

Fermez Chrome, puis relancez votre application depuis Android Studio. L'application devrait maintenant s'afficher en plein écran.

Établir une association entre le site Web et l'application

Le développeur doit collecter deux informations dans l'application pour créer l'association:

Nom du package:la première information est le nom du package de l'application. Il s'agit du même nom de package généré lors de la création de l'application. Il se trouve également dans le module build.gradle, sous Scripts Gradle > build.gradle (Module: app), et correspond à la valeur de l'attribut applicationId.
Empreinte SHA-256:les applications Android doivent être signées pour être importées sur le Play Store. La même signature est utilisée pour établir la connexion entre le site Web et l'application via l'empreinte SHA-256 de la clé d'importation.

La documentation Android explique en détail comment générer une clé à l'aide d'Android Studio. Veillez à prendre note du chemin d'accès, de l'alias et des mots de passe pour le magasin de clés, car vous en aurez besoin à l'étape suivante.

Extrayez l'empreinte SHA-256 à l'aide de keytool, avec la commande suivante:

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

La valeur de l'empreinte SHA-256 est imprimée sous la section des empreintes de certificat. Voici un exemple de résultat:

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

Avec les deux informations à portée de main, accédez au générateur de liens d'éléments, renseignez les champs et cliquez sur Generate Statement (Générer l'instruction). Copiez l'instruction générée et diffusez-la à partir de votre domaine, à partir de l'URL /.well-known/assetlinks.json.

Créer une icône

Lorsqu'Android Studio crée un projet, il est accompagné d'une icône par défaut. En tant que développeur, vous devez créer votre propre icône et différencier votre application des autres sur le lanceur Android.

Android Studio contient Image Asset Studio, qui fournit les outils nécessaires pour créer les icônes appropriées, pour chaque résolution et pour répondre aux besoins de votre application.

Dans Android Studio, accédez à File > New > Image Asset, sélectionnez Launcher Icons (Adaptative and Legacy), puis suivez les étapes de l'assistant pour créer une icône personnalisée pour l'application.

Générer un APK signé

Une fois le fichier assetlinks installé dans votre domaine et la balise asset_statements configurée dans l'application Android, l'étape suivante consiste à générer une application signée. Encore une fois, la procédure à suivre est largement documentée.

L'APK de sortie peut être installé sur un appareil de test à l'aide d'adb:

adb install app-release.apk

Si l'étape de validation échoue, vous pouvez rechercher des messages d'erreur à l'aide d'Android Debug Bridge, à partir du terminal de votre OS et avec l'appareil de test connecté.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Une fois l'APK d'importation généré, vous pouvez importer l'application sur le Play Store.

Ajouter un écran de démarrage

À partir de Chrome 75, les activités Web fiables sont compatibles avec les écrans de démarrage. Vous pouvez configurer l'écran de démarrage en ajoutant quelques fichiers image et configurations au projet.

Assurez-vous de passer à Chrome 75 ou version ultérieure et d'utiliser la dernière version de la bibliothèque d'assistance pour l'activité Web sécurisée.

Générer les images de l'écran de démarrage

Les appareils Android peuvent avoir différentes tailles d'écran et densités de pixels. Pour vous assurer que l'écran de démarrage s'affiche correctement sur tous les appareils, vous devez générer l'image pour chaque densité de pixels.

Une explication complète des pixels indépendants de l'écran (dp ou dip) dépasse le cadre de cet article, mais voici un exemple : créez une image de 320 x 320 dp, qui représente un carré de 2 x 2 pouces sur l'écran d'un appareil de n'importe quelle densité et équivaut à 320 x 320 pixels à la densité mdpi.

Nous pouvons ensuite déduire les tailles requises pour d'autres densités de pixels. Vous trouverez ci-dessous la liste des densités de pixels, le multiplicateur appliqué à la taille de base (320x320dp), la taille obtenue en pixels et l'emplacement où l'image doit être ajoutée dans le projet Android Studio.

Densité	Multiplicateur	Taille	Emplacement du projet
mdpi (référence)	x 1	320 x 320 px	/res/drawable-mdpi/
ldpi	x 0,75	240 x 240 px	/res/drawable-ldpi/
hdpi	x 1,5	480 x 480 px	/res/drawable-hdpi/
xhdpi	x 2	640x640 px	/res/drawable-xhdpi/
xxhdpi	x 3	960x960 px	/res/drawable-xxhdpi/
xxxhdpi	x4	1 280 x 1 280 px	/res/drawable-xxxhdpi/

Mettre à jour l'application

Les images de l'écran de démarrage ont été générées. Vous pouvez maintenant ajouter les configurations nécessaires au projet.

Commencez par ajouter un content-provider au fichier manifeste 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>

Ajoutez ensuite la ressource res/xml/filepaths.xml et spécifiez le chemin d'accès à l'écran de démarrage de la TWA:

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

Enfin, ajoutez meta-tags au fichier manifeste Android pour personnaliser 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>

Assurez-vous que la valeur de la balise android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY correspond à la valeur définie de l'attribut android:authorities dans la balise provider.

Rendre LauncherActivity transparent

De plus, assurez-vous que LauncherActivity est transparent pour éviter l'affichage d'un écran blanc avant l'écran de démarrage en définissant un thème translucide pour LauncherActivity:

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

Nous avons hâte de voir ce que les développeurs créeront avec les activités Web fiables. Pour nous faire part de vos commentaires, contactez-nous sur @ChromiumDev.