Guía de integración

André Cipriani Bandarra

Twitter GitHub Glitch Mastodon Página principal

Nota: Ahora se encuentra disponible una guía de inicio rápido para Trusted Web Activities.

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

Cómo crear un proyecto de actividad web de confianza

Cuando uses Trusted Web Activities, el proyecto debe orientarse al nivel de API 16 o superior.

Nota: En esta sección, aprenderás a configurar un proyecto nuevo en Android Studio. Si ya estás familiarizado con la herramienta, puedes pasar a la sección Obtén 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 Trusted Web Activities usa una actividad proporcionada por la biblioteca de compatibilidad, elige Add No Activity y haz clic en Next.

En el siguiente paso, el asistente te solicitará parámetros de configuración para el proyecto. A continuación, se incluye una descripción breve de cada campo:

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

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

Obtén la biblioteca de asistencia de Trusted Web Activity

Para configurar la biblioteca de Trusted Web Activity en el proyecto, deberás editar el archivo de compilación de la aplicación. Busca la sección Gradle Scripts en Project Navigator. Hay dos archivos llamados build.gradle, que pueden ser un poco confusos, 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 de 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
    }
}

El siguiente paso agregará la biblioteca de Trusted Web Activity Support Library al proyecto. Agrega una dependencia nueva a la sección dependencies:

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

Android Studio mostrará una solicitud para que se sincronice el proyecto una vez más. Haz clic en el vínculo Sync Now y sincronízalo.

Cómo iniciar Trusted Web Activity

La configuración de Trusted Web Activity se logra editando el Manifiesto de la app para Android.

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

Dado que le pedimos a Android Studio que no agregara ninguna actividad a nuestro proyecto al crearlo, el manifiesto está vacío y solo contiene la etiqueta de la aplicación.

Para agregar la Actividad web de confianza, 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 XML son el manifiesto de la app para Android estándar. Existen 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 de confianza.

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

En la siguiente sección, se muestra cómo configurar Digital AssetLinks para verificar la relación entre el sitio web y la app, y quitar la barra de URL.

Quitar 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 a fin de quitar la barra de URL.

Esta asociación se crea a través de Vínculos de recursos digitales, y la asociación debe establecerse de ambas maneras: es decir, se vincula desde la app hasta el sitio web y desde el sitio web hasta la app.

Con fines de depuración, es posible configurar la app para la validación de sitios web y configurar Chrome para omitir este paso.

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

Abre el archivo de recursos de cadenas app > res > values > strings.xml y agrega la siguiente declaración de Vínculos de recursos digitales:

<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 abiertos por la actividad web de confianza.

En el archivo de manifiesto de la app para Android, AndroidManifest.xml, vincula la sentencia agregando una nueva etiqueta meta-data, 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>

Ya 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 el sitio web para la validación de la aplicación.

Sigue estos pasos para probarlo en un dispositivo de desarrollo:

Cómo habilitar el modo de depuración

1. Abre Chrome en el dispositivo de desarrollo, navega a chrome://flags, busca un elemento llamado Habilitar la línea de comandos en dispositivos sin permisos de administrador, cámbialo a HABILITADO y, luego, reinicia el navegador.
2. Luego, en la aplicación de 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. Ahora, la aplicación debería mostrarse 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.

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

• Package Name: La primera información corresponde al nombre del paquete de la app. Es el mismo nombre de paquete que se generó cuando se creó la app. También se puede encontrar dentro del Module build.gradle, en Gradle Scripts > build.gradle (Module: app), y es el valor del atributo applicationId.
• Huella digital SHA-256: Las aplicaciones para Android deben firmarse para poder subirse a Play Store. La misma firma se usa 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 los necesitarás para el próximo paso.

Extrae la huella digital SHA-256 mediante la 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 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 ambos datos a mano, ve al generador de vínculos a recursos, completa los campos y presiona Generar declaración. 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 es solo el lugar en el que Chrome lo buscará.

Creación de un icono

Cuando Android Studio cree un proyecto nuevo, incluirá un ícono predeterminado. Como desarrollador, es posible que quieras crear tu propio ícono y diferenciar tu aplicación de otras en el Launcher 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 hasta 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.

Cómo generar un APK firmado

Con el archivo assetlinks implementado en tu dominio y la etiqueta asset_statements configurada en la aplicación para Android, el siguiente paso es generar una app firmada. De nuevo, los pasos a fin de hacerlo están ampliamente documentados.

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

adb install app-release.apk

Si el paso de verificación falla, es posible 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, 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. La pantalla de presentación se puede configurar agregando nuevos archivos de imagen y configuraciones al proyecto.

Asegúrate de actualizar a Chrome 75 o una versión posterior y usar la versión más reciente de la biblioteca de compatibilidad de Trusted Web Activity.

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 la densidad de cada píxel.

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 x 320 dp, que represente un cuadrado de 2 x 2 pulgadas en una pantalla de dispositivo de cualquier densidad y que sea equivalente a 320 x 320 píxeles con la densidad mdpi.

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 donde se debe agregar la imagen en el proyecto de Android Studio.

Densidad	Multiplicador	Tamaño	Ubicación del proyecto
mdpi (referencia)	× 1.0	320x320 px	/res/drawable-mdpi/
ldpi	× 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.0 veces	960x960 px	/res/drawable-xxhdpi/
xxxhdpi	4.0 veces	1280x1280 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 los 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 los parámetros de configuración necesarios al proyecto.

Primero, agrega un proveedor de contenido 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 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 lo que compilarán los desarrolladores con Trusted Web Activities. Para enviar comentarios, comunícate con nosotros a través de @ChromiumDev.