Se usó la API de Cloud Translation para traducir esta página.

Conceptos de Android (para desarrolladores web)

Peter Conn

Joyce Toh

Si eres desarrollador web y es la primera vez que trabajas con Android y Google Play, hay algunos detalles que debes tener en cuenta. Ya existen muchos recursos y documentación para esto (gracias al equipo de Android), pero aquí destacaremos algunos conceptos importantes y cómo se relacionan con Bubblewrap.

Clave de carga y clave de firma

Si planeas usar Bubblewrap para generar un Android App Bundle (AAB) (Nota: A partir de agosto de 2021, Google Play requerirá que todas las apps nuevas usen el formato Android App Bundle) o un APK para subirlo y publicarlo en Google Play, deberás firmar tu app con una clave de firma. Google Play te ofrece dos opciones para controlar esta situación:

Firma de apps de Play (muy recomendable): Google administrará y protegerá la clave de firma de tu app. La usa para firmar los APKs que se distribuirán. La firma de apps de Play usa dos claves. La "clave de firma de la app" que Google administrará por ti y la "clave de carga" que debes conservar y que debe permanecer privada. Usas la clave de carga para firmar la app y subirla a Play Console. Este sistema te permite restablecer la clave de carga si se pierde o se ve comprometida. Para ello, comunícate con el equipo de asistencia de Play. Actualmente, Google Play te permite subir tu app como un AAB o un APK:
- Android App Bundle (AAB): Cuando subes un AAB a Play Console, aplazas la compilación y generación de APKs a Google Play Store. Cuando un usuario descargue e instale tu app, Google Play la distribuirá como un APK firmado. Por lo tanto, Google Play también deberá firmar los APKs. Por lo tanto, de forma predeterminada, si subes tu app como un AAB a Play Console, se requerirá que uses la firma de apps de Play.
- APK: Con los APKs, puedes habilitar la firma de apps de Play. Se recomienda habilitar la firma de apps de Play, ya que aumenta la seguridad de tu clave de firma. Como se indicó antes, Google Play pronto requerirá que todas las apps nuevas se suban en formato AAB, por lo que te recomendamos que lo hagas en lugar de subir APKs.
Administra tu propia clave de firma: Si eliges administrar tu propia clave y no habilitar la firma de apps de Play, serás totalmente responsable de la clave de firma de tu app. A diferencia de la firma de apps de Play, no es posible restablecerla si pierdes la clave. Por lo tanto, si pierdes la clave de firma de tu app, también perderás la capacidad de actualizarla.

Durante la configuración de bubblewrap init, cuando llegues a la parte "Información de la clave de firma (5/5)", se te pedirá que ingreses una "Ubicación del almacén de claves" y un "Nombre de la clave", o que uses los valores predeterminados. La ubicación predeterminada del almacén de claves es el archivo android.keystore en el directorio de tu proyecto, y el nombre de clave predeterminado es android. Si Bubblewrap no encuentra un almacén de claves existente con ese nombre de clave en la ubicación, creará uno por ti y también te solicitará contraseñas. Anota las contraseñas que ingresaste, ya que las necesitarás durante el proceso de compilación (bubblewrap build), en el que se usará la clave para firmar tu app. Si habilitas la firma de apps de Play, la clave de firma que generó Bubblewrap y usó para firmar tu app se convierte en la "clave de carga". Ya sea que decidas usar la clave generada por Bubblewrap como clave de firma o de carga, debes protegerla y mantenerla en privado. No recomendamos confirmarlo en el control de versiones. En su lugar, limita la cantidad de personas que tienen acceso a ella.

Vínculos de recursos digitales

Los vínculos de recursos digitales son necesarios para declarar la relación entre tu sitio web y tu app para Android. Para asegurarte de que la app para Android que genera Bubblewrap se verifique correctamente y se inicie como una actividad web de confianza (en lugar de una pestaña personalizada de Chrome), deberás agregar la clave adecuada a tu archivo assetlinks.json. Luego, súbela a tu sitio web en .well-known/assetlinks.json (en relación con la raíz). Tu archivo assetlinks.json debe seguir este formato:

[{
 "relation": ["delegate_permission/common.handle_all_urls"],
 "target": {
   "namespace": "android_app",
   "package_name": "com.your.package_name",
   "sha256_cert_fingerprints": [
     "XX:XX:XX:..."
   ]
 }
}]

Obtén la huella digital del certificado SHA256

Para crear el archivo assetlinks.json, necesitarás la huella digital del certificado SHA 256 asociada con la clave de firma de tu app. Lo importante es tener en cuenta que las huellas digitales asociadas con tus claves de firma y carga serán diferentes. Es importante tener en cuenta esta distinción, en especial si observas que tu app se inicia como una pestaña personalizada de Chrome (con la barra del navegador visible). Luego, es probable que tu archivo assetlinks.json no tenga la huella dactilar que corresponde a la clave adecuada.

Es útil tener la huella dactilar de tu certificado de firma y carga en assetlinks.json para depurar tu app de forma local con mayor facilidad. Consulta Cómo agregar más claves a continuación para obtener más información sobre cómo tener ambas claves en el archivo assetlinks.json.

Existen varias maneras de obtener la huella digital, que se detallan en las siguientes secciones. Todos deberían darte las mismas huellas digitales, así que no dudes en elegir el método que te resulte más cómodo.

A través de Play Console

Según si habilitas la firma de apps de Play o no, es posible que tengas una o dos claves. Para recuperar la huella digital SHA256 adecuada para cada clave, haz lo siguiente:

Ve a Play Console.
Selecciona la app que te interesa
En el menú de navegación de la izquierda, en Versión, ve a Configuración -> Integridad de la app.
Copia el SHA256 de la clave adecuada:

Recupera la huella digital del certificado SHA256 adecuada para tu clave de firma o carga

Clave de firma: Copia la huella digital SHA256 del "Certificado de clave de firma de la app". Esta huella digital corresponderá a tu app si la descargas de Google Play Store, ya que Google Play distribuye tu app firmada con la clave de firma.
Clave de carga: Copia la huella digital SHA256 de "Upload key certificate". Esta huella digital corresponderá a tu app si la instalas de forma local (por ejemplo, a través de ADB por USB). Bubblewrap compiló ese APK (en tu máquina local) y, por lo tanto, también lo firmó con la clave que creó para ti (durante la configuración de init). Recuerda que esta puede ser la clave de firma de tu app instalada de forma local, pero en realidad se convierte en la "clave de carga" una vez que publicas la app a través de Play.

A través de `keytool`

keytool es una herramienta de administración de claves y certificados. Puedes usar keytool para extraer la huella digital SHA 256 asociada con el APK o el AAB Bubblewrap generado. Ten en cuenta que esta huella digital es para la clave de firma local y, si subes tu app a Play y habilitas la firma de apps de Play, esta clave se convierte en la "clave de carga".

keytool -printcert -jarfile [path to APK or AAB] | grep SHA256

A través de la herramienta de vinculación de recursos

Otra forma de obtener el archivo de Vínculos de recursos digitales correcto para tu app es usar la herramienta de vinculación de recursos:

Instala la herramienta de vinculación de recursos desde Play Store.
En el mismo dispositivo, descarga la app desde Google Play Store o instálala de forma local.
Abre la app de Asset Link Tool y verás una lista de todas las aplicaciones instaladas en tu dispositivo por nombre de paquete. Filtra la lista por el ID de aplicación que elegiste antes durante bubblewrap init y haz clic en esa entrada.
Verás una página en la que se muestra la firma de tu app y un vínculo de recursos digitales generado. Haz clic en los botones Copiar o Compartir en la parte inferior para exportarlo como quieras (p.ej., guardarlo en Google Keep o enviarlo por correo electrónico).

Se aplica la misma idea que antes con las claves de firma o carga. Si instalaste la app desde Google Play Store, la herramienta Asset Link te proporcionará la huella digital de la clave de firma de la app. Si instalaste la app directamente desde tu máquina local, la huella digital es para la clave que generó Bubblewrap.

Asegúrate de que se pueda acceder a tu archivo de vínculo de recursos

Ahora que lo subiste, asegúrate de poder acceder al archivo de vínculo de recursos en un navegador. Verifica que https://example.com/.well-known/assetlinks.json se resuelva en el archivo que acabas de subir.

Sitios web basados en Jekyll

Si Jekyll genera tu sitio web (como GitHub Pages), deberás agregar una línea de configuración para que el directorio .well-known se incluya en el resultado. La ayuda de GitHub tiene más información sobre este tema. Crea un archivo llamado _config.yml en la raíz de tu sitio (o agrégalo si ya existe) y ingresa lo siguiente:

# Folders with dotfiles are ignored by default.
include: [.well-known]

Cómo agregar más claves

Un archivo de Digital Asset Link puede contener más de una app y, para cada app, puede contener más de una clave. Por ejemplo, para agregar una segunda clave, usa la herramienta de vinculación de recursos para determinarla y agregarla como segunda entrada. El código de Chrome que analiza este JSON es bastante estricto, así que asegúrate de no agregar accidentalmente una coma adicional al final de la lista.

[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
},{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.your.package_name",
    "sha256_cert_fingerprints": [
      "XX:XX:XX:..."
    ]
  }
}]

Solución de problemas

Chrome registra el motivo por el que falla la verificación de Vínculos de recursos digitales, y puedes ver los registros en un dispositivo Android con adb logcat. Si desarrollas en Linux o Mac, puedes ver los registros relevantes de un dispositivo conectado con lo siguiente:

> adb logcat -v brief | grep -e OriginVerifier -e digital_asset_links

Por ejemplo, si ves el mensaje Statement failure matching fingerprint., debes usar la Herramienta de vinculación de recursos para ver la firma de tu app y asegurarte de que coincida con la del archivo assetlinks.json.