Guía de integración

André Cipriani Bandarra

Nota: Nota: Ahora está disponible una guía de inicio rápido más sencilla para Trusted Web Activities.

La configuración de una actividad web confiable no requiere que los desarrolladores escriban código Java, pero se requiere Android Studio. Esta guía se creó con Android Studio 3.3. Consulta los documentos sobre cómo instalarlo.

Crea un proyecto de actividad web de confianza

Cuando se usan actividades web de confianza, el proyecto debe tener como objetivo el nivel de API 16 o uno superior.

Nota: En esta sección, se te guiará para configurar un proyecto nuevo en Android Studio. Si ya conoces la herramienta, puedes pasar a la sección Cómo obtener la biblioteca de Trusted Web Activity.

Abre Android Studio y haz clic en Start a new Android Studio project.

Android Studio te pedirá que elijas un tipo de actividad. Dado que las actividades web de confianza usan una actividad proporcionada por la biblioteca de asistencia, elige Add No Activity y haz clic en Next.

Para el próximo paso, el asistente te pedirá configuraciones para el proyecto. A continuación, se incluye una breve descripción de cada campo:

• Nombre: Es el nombre que se usará para tu aplicación en el Selector de Android.
• Nombre del paquete: Es un identificador único para las aplicaciones para Android en Play Store y en dispositivos Android. Consulta la documentación para obtener más información sobre los requisitos y las prácticas recomendadas para crear nombres de paquetes para apps para Android.
• Ubicación de guardado: Es el lugar en el que Android Studio creará el proyecto en el sistema de archivos.
• Lenguaje: El proyecto no requiere escribir código Java ni Kotlin. Selecciona Java como la opción predeterminada.
• Nivel de API mínimo: La biblioteca de compatibilidad requiere al menos el nivel de API 16. Selecciona la API 16 o cualquier versión posterior.

Deja las casillas de verificación restantes sin marcar, ya que no usaremos apps instantáneas ni artefactos de AndroidX, y haz clic en Finalizar.

Obtén la biblioteca de compatibilidad de Trusted Web Activity

Para configurar la biblioteca de actividad web confiable en el proyecto, deberás editar el archivo de compilación de la aplicación. Busca la sección Gradle Scripts en el Project Navigator. Hay dos archivos llamados build.gradle, lo que puede ser un poco confuso, y las descripciones entre paréntesis ayudan a identificar el correcto.

El archivo que buscamos es el que tiene el módulo Module junto a su nombre.

La biblioteca Trusted Web Activities usa funciones de Java 8, y el primer cambio habilita Java 8. Agrega una sección compileOptions al final de la sección android, como se muestra a continuación:

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

En el siguiente paso, se agregará la biblioteca de compatibilidad de Trusted Web Activity al proyecto. Agrega una dependencia nueva a la sección dependencies:

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

Android Studio mostrará un mensaje en el que se te pedirá que sincronices el proyecto una vez más. Haz clic en el vínculo Sync Now y sincroniza la información.

Inicia la actividad web de confianza

Para configurar la actividad web de confianza, debes editar el manifiesto de la app para Android.

En el Project Navigator, expande la sección app, seguida de los manifiestos y haz doble clic en AndroidManifest.xml para abrir el archivo.

Como le solicitamos a Android Studio que no agregara ninguna actividad a nuestro proyecto cuando lo creamos, el manifiesto está vacío y solo contiene la etiqueta de la aplicación.

Para agregar la actividad web confiable, inserta una etiqueta activity en la etiqueta 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>

Las etiquetas que se agregan al archivo en formato XML son del manifiesto de la app para Android estándar. Hay dos datos relevantes para el contexto de Trusted Web Activities:

1. La etiqueta meta-data le indica a la actividad web de confianza qué URL debe abrir. Cambia el atributo android:value por la URL de la AWP que deseas abrir. En este ejemplo, es https://airhorner.com.
2. La segunda etiqueta intent-filter permite que la actividad web de confianza intercepte los intents de Android que abren https://airhorner.com. El atributo android:host dentro de la etiqueta data debe apuntar al dominio que abre la actividad web confiable.

Nota: Cuando ejecutes el proyecto en esta etapa, la barra de URL de las pestañas personalizadas seguirá mostrándose en la parte superior de la pantalla. Esto no es un error.

En la siguiente sección, se mostrará cómo configurar Vínculos de recursos digitales para verificar la relación entre el sitio web y la app, y cómo quitar la barra de URL.

Quita la barra de URL

Las actividades web de confianza requieren que se establezca una asociación entre la aplicación para Android y el sitio web para quitar la barra de URL.

Esta asociación se crea a través de los Vínculos de recursos digitales y se debe establecer de ambas maneras, vinculando desde la app al sitio web y desde el sitio web a la app.

Es posible configurar la validación de la app para el sitio web y configurar Chrome para que omita la validación del sitio web a la app con fines de depuración.

Establece una asociación de la app al sitio web

Abre el archivo de recursos de cadenas app > res > values > strings.xml y agrega la siguiente sentencia Digital AssetLinks:

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

Cambia el contenido del atributo site para que coincida con el esquema y el dominio que abrió Trusted Web Activity.

En el archivo de manifiesto de la app para Android, AndroidManifest.xml, agrega una nueva etiqueta meta-data para vincularla a la sentencia, pero esta vez como elemento secundario de la etiqueta 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>

Ahora establecimos una relación entre la aplicación para Android y el sitio web. Es útil depurar esta parte de la relación sin crear la validación del sitio web a la aplicación.

A continuación, te indicamos cómo probar esto en un dispositivo de desarrollo:

Habilitar modo de depuración

1. Abre Chrome en el dispositivo de desarrollo, navega a chrome://flags, busca un elemento llamado Enable command line on non-rooted devices y cámbialo a ENABLED. Luego, reinicia el navegador.
2. A continuación, en la aplicación Terminal de tu sistema operativo, usa Android Debug Bridge (instalado con Android Studio) y ejecuta el siguiente comando:

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

Cierra Chrome y vuelve a iniciar la aplicación desde Android Studio. La aplicación ahora debería aparecer en pantalla completa.

Nota: Es posible que debas forzar el cierre de Chrome para que se reinicie con la línea de comandos correcta. Ve a Configuración de Android > Apps y notificaciones > Chrome y haz clic en Forzar detención.

Establece una asociación entre el sitio web y la app

Hay 2 datos que el desarrollador debe recopilar de la app para crear la asociación:

• Nombre del paquete: La primera información es el nombre del paquete de la app. Es el mismo nombre de paquete que se genera cuando se crea la app. También se puede encontrar dentro del módulo build.gradle, en Gradle Scripts > build.gradle (Module: app), y es el valor del atributo applicationId.
• Huella digital SHA-256: Las aplicaciones para Android se deben firmar para poder subirlas a Play Store. Se usa la misma firma para establecer la conexión entre el sitio web y la app a través de la huella digital SHA-256 de la clave de carga.

En la documentación de Android, se explica en detalle cómo generar una clave con Android Studio. Asegúrate de tomar nota de la ruta de acceso, el alias y las contraseñas del almacén de claves, ya que necesitarás esta información para el siguiente paso.

Extrae la huella digital SHA-256 mediante keytool, con el siguiente comando:

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

El valor de la huella digital SHA-256 se imprime en la sección de huellas digitales de certificado. Este es un resultado de ejemplo:

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 ambas piezas de información a mano, ve al generador de assetlinks, completa los campos y presiona Generate Statement. Copia la sentencia generada y publícala desde tu dominio, desde la URL /.well-known/assetlinks.json.

Nota: El archivo AssetLinks debe estar en /.well-known/assetlinks.json, en la raíz del dominio, ya que ese es el único lugar en el que Chrome lo buscará.

Cómo crear un ícono

Cuando Android Studio cree un proyecto nuevo, tendrá un ícono predeterminado. Como desarrollador, querrás crear tu propio ícono y diferenciar tu aplicación de las demás en el selector de Android.

Android Studio contiene Image Asset Studio, que proporciona las herramientas necesarias para crear los íconos correctos para cada resolución y dar forma a las necesidades de tu aplicación.

En Android Studio, navega a File > New > Image Asset, selecciona Launcher Icons (Adaptative and Legacy) y sigue los pasos del asistente para crear un ícono personalizado para la aplicación.

Genera un APK firmado

Con el archivo assetlinks en tu dominio y la etiqueta asset_statements configurada en la aplicación para Android, el siguiente paso es generar una app firmada. Una vez más, los pasos para esto están ampliamente documentados.

El APK de salida se puede instalar en un dispositivo de prueba con adb:

adb install app-release.apk

Si el paso de verificación falla, puedes comprobar si hay mensajes de error con Android Debug Bridge, desde la terminal de tu SO y con el dispositivo de prueba conectado.

adb logcat | grep -e OriginVerifier -e digital_asset_links

Con el APK de carga generado, ahora puedes subir la app a Play Store.

Cómo agregar una pantalla de presentación

A partir de Chrome 75, Trusted Web Activities admite pantallas de presentación. Para configurar la pantalla de presentación, agrega algunos archivos de imagen y parámetros de configuración nuevos al proyecto.

Asegúrate de actualizar a Chrome 75 o una versión posterior y de usar la versión más reciente de la biblioteca de asistencia de actividad web confiable.

Cómo generar las imágenes para la pantalla de presentación

Los dispositivos Android pueden tener diferentes tamaños de pantalla y densidades de píxeles. Para garantizar que la pantalla de presentación se vea bien en todos los dispositivos, deberás generar la imagen para cada densidad de píxeles.

Una explicación completa de los píxeles independientes de la pantalla (dp o dip) está fuera del alcance de este artículo, pero un ejemplo sería crear una imagen de 320 × 320 dp, que representa un cuadrado de 5 × 5 cm en la pantalla de un dispositivo de cualquier densidad y equivale a 320 × 320 píxeles en la densidad mdpi.

A partir de allí, podemos derivar los tamaños necesarios para otras densidades de píxeles. A continuación, se muestra una lista con las densidades de píxeles, el multiplicador aplicado al tamaño base (320 x 320 dp), el tamaño resultante en píxeles y la ubicación en la que se debe agregar la imagen en el proyecto de Android Studio.

Densidad	Multiplicador	Tamaño	Ubicación del proyecto
mdpi (modelo de referencia)	× 1.0	320 x 320 px	/res/drawable-mdpi/
ldpi	x 0.75	240x240 px	/res/drawable-ldpi/
hdpi	1.5 veces	480 × 480 px	/res/drawable-hdpi/
xhdpi	2.0x	640x640 px	/res/drawable-xhdpi/
xxhdpi	3.0x	960 x 960 px	/res/drawable-xxhdpi/
xxxhdpi	4.0x	1280 x 1280 px	/res/drawable-xxxhdpi/

Nota: Una alternativa para crear todos los tamaños de imágenes es usar un elemento de diseño vectorial. Vector Asset Studio ofrece herramientas para ayudar a los desarrolladores a transformar archivos SVG en elementos de diseño vectoriales de Android.

Actualizar la aplicación

Con las imágenes de la pantalla de presentación generadas, es hora de agregar las configuraciones necesarias al proyecto.

Primero, agrega un content-provider al manifiesto de 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: Asegúrate de cambiar el atributo android:authorities cuando crees el proveedor, ya que dos aplicaciones no pueden tener la misma autoridad en un dispositivo.

Luego, agrega el recurso res/xml/filepaths.xml y especifica la ruta de acceso a la pantalla de presentación de TWA:

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

Por último, agrega meta-tags al manifiesto de Android para personalizar 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>

Asegúrate de que el valor de la etiqueta android.support.customtabs.trusted.FILE_PROVIDER_AUTHORITY coincida con el valor definido del atributo android:authorities dentro de la etiqueta provider.

Cómo hacer que LauncherActivity sea transparente

Además, asegúrate de que el elemento LauncherActivity sea transparente para evitar que se muestre una pantalla blanca antes de la presentación. Para ello, configura un tema translúcido para LauncherActivity:

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

Esperamos ver qué crean los desarrolladores con Trusted Web Activities. Si quieres enviarnos tus comentarios, escríbenos a @ChromiumDev.