Deep Linking

GitHubnpmcrates.io

Referencia de API

Establece tu aplicación Tauri como el manejador predeterminado para una URL.

Plataformas Soportadas

Este plugin requiere una versión de Rust de al menos 1.77.2

Plataforma	Nivel	Notas
windows
linux
macos		Los deep links deben registrarse en la configuración. El registro dinámico en tiempo de ejecución no es compatible.
android		Los deep links deben registrarse en la configuración. El registro dinámico en tiempo de ejecución no es compatible.
ios		Los deep links deben registrarse en la configuración. El registro dinámico en tiempo de ejecución no es compatible.

Configuración

Instala el plugin deep-link para comenzar.

Automático

Usa el gestor de paquetes de tu proyecto para agregar la dependencia:

npm

npm run tauri add deep-link

yarn

yarn run tauri add deep-link

pnpm

pnpm tauri add deep-link

deno

deno task tauri add deep-link

bun

bun tauri add deep-link

cargo

cargo tauri add deep-link

Manual

1. Ejecuta el siguiente comando en la carpeta src-tauri para agregar el plugin a las dependencias del proyecto en Cargo.toml:

   cargo add tauri-plugin-deep-link@2.0.0

2. Modifica lib.rs para inicializar el plugin:

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
   pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_deep_link::init())
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. Instala los bindings de JavaScript utilizando tu gestor de paquetes de JavaScript preferido:

   npm

   npm install @tauri-apps/plugin-deep-link

   yarn

   yarn add @tauri-apps/plugin-deep-link

   pnpm

   pnpm add @tauri-apps/plugin-deep-link

   deno

   deno add npm:@tauri-apps/plugin-deep-link

   bun

   bun add @tauri-apps/plugin-deep-link

Configuración

Android

Hay dos formas de abrir tu aplicación desde enlaces en Android:

1. App Links (http/https + host, verificado) Para app links, necesitas un servidor con un endpoint .well-known/assetlinks.json que debe devolver una respuesta de texto en el formato dado:

.well-known/assetlinks.json

[
  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "$APP_BUNDLE_ID",
      "sha256_cert_fingerprints": [
        $CERT_FINGERPRINT
      ]
    }
  }
]

Donde $APP_BUNDLE_ID es el valor definido en tauri.conf.json > identifier con - reemplazado por _ y $CERT_FINGERPRINT es una lista de huellas digitales SHA256 de los certificados de firma de tu aplicación, consulta verificar Android applinks para más información.

2. Esquemas URI personalizados (no requiere host, sin verificación) Para URIs como myapp://..., puedes declarar un esquema personalizado sin alojar ningún archivo. Usa el campo scheme en la configuración móvil y omite el host.

iOS

Hay dos formas de abrir tu aplicación desde enlaces en iOS:

1. Universal Links (https + host, verificado) Para universal links, necesitas un servidor con un endpoint .well-known/apple-app-site-association que debe devolver una respuesta JSON en el formato dado:

.well-known/apple-app-site-association

{
  "applinks": {
    "details": [
      {
        "appIDs": ["$DEVELOPMENT_TEAM_ID.$APP_BUNDLE_ID"],
        "components": [
          {
            "/": "/open/*",
            "comment": "Matches any URL whose path starts with /open/"
          }
        ]
      }
    ]
  }
}

Nota

El encabezado Content-Type de la respuesta debe ser application/json.

El endpoint .well-known/apple-app-site-association debe servirse a través de HTTPS. Para probar en localhost puedes usar un certificado TLS autofirmado e instalarlo en el simulador de iOS o usar servicios como ngrok.

Donde $DEVELOPMENT_TEAM_ID es el valor definido en tauri.conf.json > bundle > iOS > developmentTeam o la variable de entorno TAURI_APPLE_DEVELOPMENT_TEAM y $APP_BUNDLE_ID es el valor definido en tauri.conf.json > identifier.

Para verificar si tu dominio se ha configurado correctamente para exponer las asociaciones de la app, puedes ejecutar el siguiente comando, reemplazando <host> con tu host real:

curl -v https://app-site-association.cdn-apple.com/a/v1/<host>

Consulta applinks.details para más información.

2. Esquemas URI personalizados (sin host, sin verificación) Para URIs como myapp://..., puedes declarar un esquema personalizado bajo la configuración móvil con "appLink": false (o omitirlo). El plugin genera las entradas CFBundleURLTypes apropiadas en el Info.plist de tu aplicación. No se necesitan archivos .well-known ni host HTTPS.

Escritorio

En Linux y Windows los deep links se entregan como un argumento de línea de comandos a un nuevo proceso de la aplicación. El plugin deep link tiene integración con el plugin single instance si prefieres tener una única instancia de la aplicación recibiendo los eventos.

• Primero debes agregar la característica deep-link al plugin single instance:

src-tauri/Cargo.toml

[target."cfg(any(target_os = \"macos\", windows, target_os = \"linux\"))".dependencies]
tauri-plugin-single-instance = { version = "2.0.0", features = ["deep-link"] }

• Luego configura el plugin single instance, que siempre debe ser el primer plugin que registres:

src-tauri/lib.rs

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    let mut builder = tauri::Builder::default();

    #[cfg(desktop)]
    {
        builder = builder.plugin(tauri_plugin_single_instance::init(|_app, argv, _cwd| {
          println!("a new app instance was opened with {argv:?} and the deep link event was already triggered");
          // when defining deep link schemes at runtime, you must also check `argv` here
        }));
    }

    builder = builder.plugin(tauri_plugin_deep_link::init());
}

Precaución

El usuario podría activar un deep link falso manualmente incluyendo la URL como argumento. Tauri compara el argumento de la línea de comandos con los esquemas configurados para mitigar esto, pero aún así deberías verificar si la URL coincide con el formato que esperas.

Esto significa que Tauri solo maneja deep links para esquemas que fueron configurados estáticamente, y los esquemas registrados en tiempo de ejecución deben verificarse manualmente usando Env::args_os.

Configuración

En tauri.conf.json > plugins > deep-link, configura dominios/esquemas móviles y esquemas de escritorio que quieras asociar con tu aplicación.

Ejemplos

Esquema personalizado en móviles (no requiere servidor):

tauri.conf.json

{
  "plugins": {
    "deep-link": {
      "mobile": [
        {
          "scheme": ["ovi"],
          "appLink": false
        }
      ]
    }
  }
}

Esto registra el esquema ovi://* en Android y iOS.

App Link / Universal Link (https + host verificado):

{
  "plugins": {
    "deep-link": {
      "mobile": [
        {
          "scheme": ["https"],
          "host": "your.website.com",
          "pathPrefix": ["/open"],
          "appLink": true
        }
      ]
    }
  }
}

Esto registra https://your.website.com/open/* como un app/universal link.

Desktop custom schemes:

{
  "plugins": {
    "deep-link": {
      "desktop": {
        "schemes": ["something", "my-tauri-app"]
      }
    }
  }
}

Uso

El plugin deep-link está disponible tanto en JavaScript como en Rust.

Escuchar Deep Links

JavaScript

Cuando un deep link activa tu aplicación mientras se está ejecutando, se llama al callback onOpenUrl. Para detectar si tu aplicación se abrió mediante un deep link, usa getCurrent al iniciar la aplicación.

import { getCurrent, onOpenUrl } from '@tauri-apps/plugin-deep-link';
// when using `"withGlobalTauri": true`, you may use
// const { getCurrent, onOpenUrl } = window.__TAURI__.deepLink;

const startUrls = await getCurrent();
if (startUrls) {
  // App was likely started via a deep link
  // Note that getCurrent's return value will also get updated every time onOpenUrl gets triggered.
}

await onOpenUrl((urls) => {
  console.log('deep link:', urls);
});

Rust

Cuando un deep link activa tu aplicación mientras se está ejecutando, se llama al closure on_open_url del plugin. Para detectar si tu aplicación se abrió mediante un deep link, usa get_current al iniciar la aplicación.

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            // Note that get_current's return value will also get updated every time on_open_url gets triggered.
            let start_urls = app.deep_link().get_current()?;
            if let Some(urls) = start_urls {
                // app was likely started by a deep link
                println!("deep link URLs: {:?}", urls);
            }

            app.deep_link().on_open_url(|event| {
                println!("deep link URLs: {:?}", event.urls());
            });
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Nota

El evento de apertura de URL se activa con una lista de URLs que se solicitaron para ser compatibles con la API de macOS para deep links, pero en la mayoría de los casos tu aplicación solo recibirá una única URL.

Registrar Deep Links de Escritorio en Tiempo de Ejecución

La sección de configuración describe cómo definir esquemas de deep link estáticos para tu aplicación.

En Linux y Windows también es posible asociar esquemas con tu aplicación en tiempo de ejecución a través de la función de Rust register.

En el siguiente fragmento, registraremos el esquema my-app en tiempo de ejecución. Después de ejecutar la aplicación por primera vez, el sistema operativo abrirá las URLs my-app://* con nuestra aplicación:

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(desktop)]
            app.deep_link().register("my-app")?;
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Nota

Registrar los deep links en tiempo de ejecución puede ser útil para el desarrollo en Linux y Windows, ya que por defecto el deep link solo se registra cuando se instala tu aplicación.

Instalar un AppImage puede ser complicado ya que requiere un lanzador de AppImage.

Registrar los deep links en tiempo de ejecución puede ser preferible, por lo que Tauri también incluye una función auxiliar para forzar el registro de todos los deep links configurados estáticamente en tiempo de ejecución. Llamar a esta función también garantiza que los deep links estén registrados para el modo de desarrollo:

#[cfg(any(target_os = "linux", all(debug_assertions, windows)))]
{
  use tauri_plugin_deep_link::DeepLinkExt;
  app.deep_link().register_all()?;
}

Pruebas

Hay algunas advertencias al probar deep links para tu aplicación.

Escritorio

Los deep links solo se activan para aplicaciones instaladas en escritorio. En Linux y Windows puedes eludir esto usando la función de Rust register_all, la cual registra todos los esquemas configurados para activar el ejecutable actual:

src-tauri/src/lib.rs

use tauri_plugin_deep_link::DeepLinkExt;

#[cfg_attr(mobile, tauri::mobile_entry_point)]
pub fn run() {
    tauri::Builder::default()
        .plugin(tauri_plugin_deep_link::init())
        .setup(|app| {
            #[cfg(any(windows, target_os = "linux"))]
            {
                use tauri_plugin_deep_link::DeepLinkExt;
                app.deep_link().register_all()?;
            }
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Nota

Instalar un AppImage que admita deep links en Linux requiere un lanzador de AppImage para integrar el AppImage con el sistema operativo. Usando la función register_all puedes admitir deep links directamente, sin requerir que tus usuarios usen herramientas externas.

Cuando el AppImage se mueve a una ubicación diferente en el sistema de archivos, el deep link se invalida ya que aprovecha una ruta absoluta al ejecutable, lo que hace que registrar los esquemas en tiempo de ejecución sea aún más importante.

Consulta la sección Registrar Deep Links de Escritorio en Tiempo de Ejecución para obtener más información.

Precaución

Registrar deep links en tiempo de ejecución no es posible en macOS, por lo que los deep links solo se pueden probar en la aplicación empaquetada, la cual debe estar instalada en el directorio /Applications.

Ventanas

Para activar un deep link en Windows puedes abrir <scheme>://url en el navegador o ejecutar el siguiente comando en la terminal:

start <scheme>://url

Linux

Para activar un deep link en Linux puedes abrir <scheme>://url en el navegador o ejecutar xdg-open en la terminal:

xdg-open <scheme>://url

iOS

Para activar un app link en iOS puedes abrir la URL https://<host>/path en el navegador. Para simuladores puedes aprovechar la CLI de simctl para abrir directamente un enlace desde la terminal:

xcrun simctl openurl booted https://<host>/path

Android

Para activar un app link en Android puedes abrir la URL https://<host>/path en el navegador. Para emuladores puedes aprovechar la CLI de adb para abrir directamente un enlace desde la terminal:

adb shell am start -a android.intent.action.VIEW -d https://<host>/path <bundle-identifier>

Permisos

De forma predeterminada, todos los comandos y alcances (scopes) potencialmente peligrosos del plugin están bloqueados y no se puede acceder a ellos. Debes modificar los permisos en tu configuración de capabilities para habilitarlos.

Consulta la Visión General de Capacidades para obtener más información y la guía paso a paso para usar permisos de plugins.

src-tauri/capabilities/default.json

{
  "$schema": "../gen/schemas/mobile-schema.json",
  "identifier": "mobile-capability",
  "windows": ["main"],
  "platforms": ["iOS", "android"],
  "permissions": [
    // Usually you will need core:event:default to listen to the deep-link event
    "core:event:default",
    "deep-link:default"
  ]
}

Permiso Predeterminado

Permite leer el deep link abierto mediante el comando get_current

Este conjunto de permisos predeterminado incluye lo siguiente:

• allow-get-current

Tabla de Permisos

Identificador	Descripción
deep-link:allow-get-current	Habilita el comando get_current sin ningún ámbito preconfigurado.
deep-link:deny-get-current	Deniega el comando get_current sin ningún ámbito preconfigurado.
deep-link:allow-is-registered	Habilita el comando is_registered sin ningún ámbito preconfigurado.
deep-link:deny-is-registered	Deniega el comando is_registered sin ningún ámbito preconfigurado.
deep-link:allow-register	Habilita el comando register sin ningún ámbito preconfigurado.
deep-link:deny-register	Deniega el comando register sin ningún ámbito preconfigurado.
deep-link:allow-unregister	Habilita el comando unregister sin ningún ámbito preconfigurado.
deep-link:deny-unregister	Deniega el comando unregister sin ningún ámbito preconfigurado.