Compartir a través de

Vínculos de aplicaciones de Android

  • Artículo

A menudo es conveniente conectar un sitio web y una aplicación móvil para que los vínculos en un sitio web inicien la aplicación móvil y muestren contenido en la aplicación móvil. La vinculación de aplicaciones, también conocida como vinculación en profundidad, es una técnica que habilita un dispositivo móvil para responder a un URI e iniciar el contenido de una aplicación móvil representada por la URI.

Android controla los vínculos de la aplicación a través del sistema de intenciones. Al pulsar un vínculo en un explorador móvil, el explorador enviará una intención que Android delegará en una aplicación registrada. Estos vínculos pueden basarse en un esquema personalizado, como myappname://, o pueden usar el esquema HTTP o HTTPS. Por ejemplo, al hacer clic en un vínculo de un sitio web de recetas se abriría una aplicación móvil asociada a ese sitio web, y después se mostraría una receta concreta al usuario. Si hay más de una aplicación registrada para manejar la intención, Android mostrará un diálogo de desambiguación que preguntará al usuario qué aplicación debe seleccionar para manejar la intención. Los usuarios que no tienen instalada la aplicación se llevan al contenido de su sitio web.

Android clasifica los vínculos de la aplicación en tres categorías:

  • Los vínculos profundos son URI de cualquier esquema que llevan a los usuarios a contenidos específicos de su aplicación. Cuando se hace clic en un vínculo profundo, puede aparecer un cuadro de diálogo de desambiguación que pide al usuario que seleccione una aplicación para controlar el vínculo profundo.
  • Los vínculos web son vínculos profundos que usan el esquema HTTP o HTTPS. En Android 12 y versiones superiores, un vínculo web siempre muestra el contenido en un explorador web. En versiones anteriores de Android, si una aplicación puede manejar el vínculo web, aparecerá un cuadro de diálogo de desambiguación que pedirá al usuario que seleccione una aplicación para manejar el vínculo web.
  • Los vínculos de aplicaciones Android, que están disponibles en la API 23+, son vínculos web que usan el esquema HTTP o HTTPS y contienen el atributo autoVerify. Este atributo habilita a su aplicación para convertirse en el controlador predeterminado de un vínculo de aplicación. Por lo tanto, cuando se hace clic en el vínculo de una aplicación, la aplicación se abre sin mostrar un cuadro de diálogo de desambiguación.

Las aplicaciones .NET MAUI para Android pueden ser compatibles con las tres categorías de vínculos de aplicaciones. Sin embargo, este artículo se centra en los vínculos de aplicaciones de Android. Esto requiere demostrar la propiedad de un dominio, así como hospedar un archivo JSON de vínculos de recursos digitales en el dominio, que describe la relación con la aplicación. Esto permite a Android comprobar que la aplicación que intenta controlar una dirección URI tiene propiedad del dominio de direcciones URI para evitar que las aplicaciones malintencionadas intercepten los vínculos de la aplicación.

El proceso para controlar los vínculos de aplicaciones de Android en una aplicación .NET MAUI para Android es el siguiente:

  1. Comprobar la propiedad del dominio. Para más información, consulte Comprobación de la propiedad del dominio.
  2. Cree y hospede un archivo de vínculos de recursos digitales en su sitio web. Para más información, consulte Creación y hospedaje de un archivo de vínculos de recursos digitales.
  3. Configure un filtro de intención en la aplicación para los URI del sitio web. Para más información, consulte Configuración del filtro de intenciones.
  4. Leer los datos de la intención entrante. Para más información, consulte Leer los datos de la intención entrante.

Importante

Para usar los vínculos de aplicación de Android:

  • Una versión de la aplicación debe estar activa en Google Play.
  • El sitio web complementario debe estar registrado junto a la aplicación en la Consola para desarrolladores de Google. Una vez que la aplicación está asociada a un sitio web, se pueden indexar URI que funcionen tanto para el sitio web como para la aplicación, que después se pueden servir en los resultados de búsqueda. Para más información, consulte Indización de aplicaciones en la Búsqueda de Google en support.google.com.

Para más información sobre los vínculos de aplicaciones Android, consulte Cómo controlar los vínculos de aplicaciones Android.

Comprobar la propiedad del dominio

Se le pedirá que verifique la propiedad del dominio desde el que está sirviendo los vínculos de la aplicación en Google Search Console. La verificación de la propiedad significa demostrar que usted es el propietario de un sitio web concreto. Google Search Console es compatible con varios métodos de verificación. Para más información, consulte el Comprobación de la propiedad de su sitio en support.google.com.

Los vínculos de aplicaciones Android requieren que Android verifique la asociación entre la aplicación y el sitio web antes de establecer la aplicación como controlador predeterminado para el URI. Esta comprobación se producirá cuando la aplicación se instale por primera vez. El archivo de vínculos de recursos digitales es un archivo JSON que debe estar hospedado por el dominio web correspondiente en la siguiente ubicación: https://domain.name/.well-known/assetlinks.json.

El archivo del recurso digital contiene los metadatos necesarios para que Android verifique la asociación. El archivo requiere los siguientes pares clave-valor:

  • namespace: el espacio de nombres de la aplicación Android.
  • package_name: el nombre del paquete de la aplicación Android.
  • sha256_cert_fingerprints: las huellas digitales SHA256 de la aplicación firmada, obtenida del archivo .keystore. Para obtener información sobre cómo ver la firma de su almacén de claves, consulte Cómo ver la firma de su almacén de claves.

El siguiente archivo assetlinks.json de ejemplo concede derechos de apertura de vínculos a una aplicación de Android com.companyname.myrecipeapp:

[
   {
      "relation": [
         "delegate_permission/common.handle_all_urls"
      ],
      "target": {
         "namespace": "android_app",
         "package_name": "com.companyname.myrecipeapp",
         "sha256_cert_fingerprints": [
            "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
         ]
      }
   }
]

Es posible registrar más de una huella digital SHA256 para admitir diferentes versiones o compilaciones de la aplicación. El siguiente archivo assetlinks.json concede derechos de apertura de vínculos tanto a las aplicaciones de Android de com.companyname.myrecipeapp como a las de com.companyname.mycookingapp:

[
   {
      "relation": [
         "delegate_permission/common.handle_all_urls"
      ],
      "target": {
         "namespace": "android_app",
         "package_name": "com.companyname.myrecipeapp",
         "sha256_cert_fingerprints": [
            "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
         ]
      }
   },
   {
      "relation": [
         "delegate_permission/common.handle_all_urls"
      ],
      "target": {
         "namespace": "android_app",
         "package_name": "com.companyname.mycookingapp",
         "sha256_cert_fingerprints": [
            "14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"
         ]
      }
   }
]

Sugerencia

Use la herramienta Generador de listas de instrucciones y evaluador para ayudar a generar el JSON correcto y para validarlo.

Al publicar su archivo de verificación JSON en https://domain.name/.well-known/assetlinks.json, debe asegurarse de que:

  • El archivo se sirve con tipo de contenido application/json.
  • El archivo debe ser accesible a través de HTTPS, independientemente de si su aplicación usa HTTPS como esquema.
  • El archivo debe ser accesible sin redireccionamientos.
  • Si los vínculos de su aplicación son compatibles con varios dominios, deberá publicar el archivo assetlinks.json en cada dominio.

Puede confirmar que el archivo de recursos digitales tiene el formato y el alojamiento adecuados usando la API de vínculos de recursos digitales de Google:

https://digitalassetlinks.googleapis.com/v1/statements:list?source.web.site=
  https://<WEB SITE ADDRESS>:&relation=delegate_permission/common.handle_all_urls

Para más información, consulte Declarar asociaciones de sitios web en developer.android.com.

Configuración del filtro de intención

Debe configurarse un filtro de intenciones que asigne un URI, o un conjunto de URI, de un sitio web a una actividad de su aplicación Android. En .NET MAUI, esto se puede conseguir añadiendo IntentFilterAttribute a su actividad. El filtro de intención debe declarar la siguiente información:

  • ActionView: esto registrará el filtro de intención para responder a las solicitudes para ver información.
  • Categories: el filtro de intención debe registrar tanto CategoryDefault como CategoryBrowsable para poder controlar correctamente el URI web.
  • DataScheme: el filtro de intención debe declarar un esquema personalizado y/o HTTPS.
  • DataHost: este es el dominio desde el que se originarán los URI.
  • DataPathPrefix: esta es una ruta de acceso opcional a los recursos del sitio web, que debe comenzar con un /.
  • AutoVerify: indica a Android que compruebe la relación entre la aplicación y el sitio web. Debe establecerse en true, de lo contrario Android no verificará la asociación entre la aplicación y el sitio web y, por tanto, no establecerá su aplicación como controlador predeterminado de un URI.

El siguiente ejemplo muestra cómo usar el IntentFilterAttribute para controlar los vínculos de https://www.recipe-app.com/recipes:

using Android.App;
using Android.Content;
using Android.Content.PM;

namespace MyNamespace;

[Activity(
    Theme = "@style/Maui.SplashTheme",
    MainLauncher = true,
    ConfigurationChanges = ConfigChanges.ScreenSize |
        ConfigChanges.Orientation |
        ConfigChanges.UiMode |
        ConfigChanges.ScreenLayout |
        ConfigChanges.SmallestScreenSize |
        ConfigChanges.KeyboardHidden |
        ConfigChanges.Density)]
[IntentFilter(
    new string[] { Intent.ActionView },
    Categories = new[] { Intent.CategoryDefault, Intent.CategoryBrowsable },
    DataScheme = "https",
    DataHost = "recipe-app.com",
    DataPath = "/recipe",
    AutoVerify = true,)]    
public class MainActivity : MauiAppCompatActivity
{
}

Nota:

Se pueden especificar varios esquemas y hosts en el filtro de intención. Para más información, consulte Creación de vínculos profundos al contenido de la aplicación en developer.android.com.

Android verificará cada host que se identifique en los filtros de intenciones con el archivo de recursos digitales del sitio web, antes de registrar la aplicación como controlador predeterminado de un URI. Todos los filtros de intención deben pasar la comprobación antes de que Android pueda establecer la aplicación como el controlador predeterminado. Una vez que haya agregado un filtro de intención con un URI para el contenido de la actividad, Android podrá enrutar cualquier intención que tenga URI coincidentes a su aplicación en runtime.

También puede ser necesario marcar su actividad como exportable, para que pueda ser iniciada por otras aplicaciones. Esto puede lograrse añadiendo Exported = true al ActivityAttribute existente. Para más información, consulte Elemento de actividad en developer.android.com.

Cuando se invoca una intención URI web, Android intenta las siguientes acciones hasta que la solicitud tiene éxito:

  1. Abre la aplicación preferida para controlar el URI.
  2. Abre la única aplicación disponible para controlar el URI.
  3. Permite al usuario seleccionar una aplicación para controlar el URI.

Para más información sobre las intenciones y los filtros de intenciones, consulte Intenciones y filtros de intenciones en developer.android.com.

Leer los datos de la intención entrante

Cuando Android inicia su actividad a través de un filtro de intención, puede usar los datos proporcionados por la intención para determinar qué hacer. Esto debe realizarse en un delegado de ciclo de vida temprano, idealmente OnCreate. El delegado de OnCreate se invoca cuando se crea una actividad. Para más información sobre los delegados del ciclo de vida, consulte Eventos del ciclo de vida de la plataforma.

Para responder a la invocación de un delegado de ciclo de vida de Android, llama al método ConfigureLifecycleEvents en el objeto MauiAppBuilder del método MauiProgram de la clase CreateMauiapp. Después, en el objeto ILifecycleBuilder, llame al método AddAndroid y especifique el Action que registra un controlador para el delegado requerido:

using Microsoft.Maui.LifecycleEvents;
using Microsoft.Extensions.Logging;

namespace MyNamespace;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            })
            .ConfigureLifecycleEvents(lifecycle =>
            {
#if ANDROID
                lifecycle.AddAndroid(android =>
                {
                    android.OnCreate((activity, bundle) =>
                    {
                        var action = activity.Intent?.Action;
                        var data = activity.Intent?.Data?.ToString();

                        if (action == Android.Content.Intent.ActionView && data is not null)
                        {
                            Task.Run(() => HandleAppLink(data));
                        }
                    });
                });
#endif
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }

    static void HandleAppLink(string url)
    {
        if (Uri.TryCreate(url, UriKind.RelativeOrAbsolute, out var uri))
            App.Current?.SendOnAppLinkRequestReceived(uri);
    }
}

La propiedad Intent.Action recupera la acción asociada a la intención entrante, y la propiedad Intent.Data recupera los datos asociados a la intención entrante. Siempre que la acción de la intención se establezca en ActionView, los datos de la intención pueden pasarse a su clase App con el método SendOnAppLinkRequestReceived.

Advertencia

Los vínculos de aplicaciones ofrecen un vector de ataque potencial a su aplicación, por lo que debe asegurarse de validar todos los parámetros de URI y descartar cualquier URI malformado.

En la clase App, invalide el método OnAppLinkRequestReceived para recibir y procesar los datos de la intención:

namespace MyNamespace;

public partial class App : Application
{
    ...

    protected override async void OnAppLinkRequestReceived(Uri uri)
    {
        base.OnAppLinkRequestReceived(uri);

        // Show an alert to test that the app link was received.
        await Dispatcher.DispatchAsync(async () =>
        {
            await Windows[0].Page!.DisplayAlert("App link received", uri.ToString(), "OK");
        });

        Console.WriteLine("App link: " + uri.ToString());
    }
}

En el ejemplo anterior, la invalidación de OnAppLinkRequestReceived muestra el URI del vínculo de la aplicación. En la práctica, el vínculo de la aplicación debe llevar a los usuarios directamente al contenido representado por el URI, sin solicitudes, inicios de sesión u otras interrupciones. Por lo tanto, la invalidación de OnAppLinkRequestReceived es la ubicación desde la que se invoca la navegación hacia el contenido representado por el URI.

Siempre que el archivo de recursos digitales esté correctamente hospedado, puede usar Android Debug Bridge, adb, con la herramienta del administrador de actividades, am, para simular la apertura de un URI y asegurarse de que los vínculos de aplicación funcionan correctamente. Por ejemplo, el siguiente comando intenta ver la actividad de una aplicación de destino asociada a un URI:

adb shell am start -W -a android.intent.action.VIEW -c android.intent.category.BROWSABLE -d YOUR_URI_HERE

Este comando enviará una intención que Android deberá dirigir a su aplicación móvil, que deberá iniciar y mostrar la actividad registrada para el URI.

Nota:

Puede ejecutar adb mediante un emulador o un dispositivo.

Además, puede visualizar las directivas de control de vínculos existentes para las aplicaciones instaladas en un dispositivo:

adb shell dumpsys package domain-preferred-apps

Este comando mostrará la siguiente información:

  • Paquete: nombre del paquete de la aplicación.
  • Dominio: los dominios, separados por espacios, cuyos vínculos web se controlarán mediante la aplicación.
  • Estado: el estado actual del control de vínculos para la aplicación. Un valor de always significa que la aplicación ha establecido AutoVerify en true y ha pasado la verificación del sistema. Le sigue un número hexadecimal que representa el registro de la preferencia.

Para más información sobre el comando adb, consulte Android Debug Bridge.

Además, puede administrar y verificar los vínculos de aplicaciones Android a través de Play Console. Para más información, consulte Administración y comprobación de vínculos de aplicaciones Android en developer.android.com.

Para ver consejos sobre cómo solucionar problemas, consulte Corrección de errores comunes de implementación en developer.android.com.