NFC

GitHubnpmcrates.io

Referencia de API

Lee y escribe etiquetas NFC en Android e iOS.

Plataformas Soportadas

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

Plataforma	Nivel	Notas
windows
linux
macos
android
ios

Configuración

Instala el plugin nfc para comenzar.

Automático

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

npm

npm run tauri add nfc

yarn

yarn run tauri add nfc

pnpm

pnpm tauri add nfc

bun

bun tauri add nfc

cargo

cargo tauri add nfc

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-nfc --target 'cfg(any(target_os = "android", target_os = "ios"))'

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()
           .setup(|app| {
               #[cfg(mobile)]
               app.handle().plugin(tauri_plugin_nfc::init());
               Ok(())
           })
           .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-nfc

   yarn

   yarn add @tauri-apps/plugin-nfc

   pnpm

   pnpm add @tauri-apps/plugin-nfc

   deno

   deno add npm:@tauri-apps/plugin-nfc

   bun

   bun add @tauri-apps/plugin-nfc

Configuración

El plugin NFC requiere configuración nativa para iOS.

iOS

Para acceder a las API de NFC en iOS debes ajustar la versión objetivo de iOS, configurar una descripción de uso en el archivo Info.plist y añadir la capacidad de NFC a tu aplicación.

Versión objetivo de iOS

El plugin NFC requiere iOS 14+. Este es el valor por defecto para las aplicaciones Tauri creadas con la CLI de Tauri v2.8 y superior, pero puedes editar tu proyecto de Xcode para configurarlo.

En el archivo src-tauri/gen/apple/<project-name>.xcodeproj/project.pbxproj, establece todas las propiedades IPHONEOS_DEPLOYMENT_TARGET en 14.0:

src-tauri/gen/apple/<project-name>.xcodeproj/project.pbxproj

/* Begin XCBuildConfiguration section */
    1234567890ABCDEF12345678 /* release */ = {
      isa = XCBuildConfiguration;
      buildSettings = {
        /* ... */
        IPHONEOS_DEPLOYMENT_TARGET = 14.0;
      };
      name = release;
    };
    ABCDEF1234567890ABCDEF12 /* debug */ = {
      isa = XCBuildConfiguration;
      buildSettings = {
        /* ... */
        IPHONEOS_DEPLOYMENT_TARGET = 14.0;
      };
      name = debug;
    };

Alternativamente puedes establecer el objetivo de despliegue desde Xcode en la configuración General > Minimum Deployments > iOS.

Info.plist

En iOS el plugin NFC requiere el valor de propiedad de información NFCReaderUsageDescription en Info.plist, el cual debe describir por qué tu aplicación necesita escanear o escribir en etiquetas NFC.

En el archivo src-tauri/Info.ios.plist, agrega el siguiente fragmento:

src-tauri/Info.ios.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>NFCReaderUsageDescription</key>
    <string>Read and write various NFC tags</string>
  </dict>
</plist>

Capacidad de NFC

Adicionalmente iOS requiere que la capacidad de NFC esté asociada con tu aplicación.

La capacidad se puede añadir en Xcode en la pestaña «Signing & Capabilities» de la configuración del proyecto haciendo clic en el botón «+ Capability» y seleccionando la capacidad «Near Field Communication Tag Reading» (consulta Añadir una capacidad a un objetivo para más información) o añadiendo la siguiente configuración al archivo gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements:

gen/apple/<app-name>_iOS/<app-name>_iOS.entitlements

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>com.apple.developer.nfc.readersession.formats</key>
  <array>
    <string>TAG</string>
  </array>
</dict>
</plist>

Uso

El plugin NFC está disponible tanto en JavaScript como en Rust, lo que te permite escanear y escribir en etiquetas NFC.

Comprobar si NFC es compatible

No todos los dispositivos móviles tienen la capacidad de escanear etiquetas NFC, por lo que debes comprobar la disponibilidad antes de usar las API de escaneo y escritura.

JavaScript

import { isAvailable } from '@tauri-apps/plugin-nfc';

const canScanNfc = await isAvailable();

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let can_scan_nfc = app.nfc().is_available()?;
    }
    Ok(())
  })

Escanear etiquetas NFC

El plugin puede escanear tanto etiquetas NFC genéricas como etiquetas NFC con un mensaje NDEF (NFC Data Exchange Format), el cual es un formato estándar para encapsular datos tipados en una etiqueta NFC.

JavaScript

import { scan } from '@tauri-apps/plugin-nfc';

const scanType = {
  type: 'ndef', // or 'tag',
};

const options = {
  keepSessionAlive: false,
  // configure the messages displayed in the "Scan NFC" dialog on iOS
  message: 'Scan a NFC tag',
  successMessage: 'NFC tag successfully scanned',
};

const tag = await scan(scanType, options);

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let tag = app
        .nfc()
        .scan(tauri_plugin_nfc::ScanRequest {
            kind: tauri_plugin_nfc::ScanKind::Ndef {
                mime_type: None,
                uri: None,
                tech_list: None,
            },
            keep_session_alive: false,
        })?
        .tag;
    }
    Ok(())
  })

Nota

La opción keepSessionAlive se puede utilizar para escribir directamente en la etiqueta NFC escaneada más adelante.

Si no proporcionas esa opción, la sesión se vuelve a crear en la siguiente llamada a write(), lo que significa que la aplicación intentará volver a escanear la etiqueta.

Filtros

El escáner NFC también puede filtrar etiquetas con un formato URI específico, tipo mime o tecnologías de etiquetas NFC. En este caso, el escaneo solo detectará etiquetas que coincidan con los filtros proporcionados.

Nota

El filtrado solo está disponible en Android, por lo que siempre debes comprobar los contenidos de la etiqueta NFC escaneada.

El tipo mime distingue entre mayúsculas y minúsculas y debe proporcionarse con letras minúsculas.

JavaScript

import { scan, TechKind } from '@tauri-apps/plugin-nfc';

const techLists = [
  // capture anything using NfcF
  [TechKind.NfcF],
  // capture all MIFARE Classics with NDEF payloads
  [TechKind.NfcA, TechKind.MifareClassic, TechKind.Ndef],
];

const tag = await scan({
  type: 'ndef', // or 'tag'
  mimeType: 'text/plain',
  uri: {
    scheme: 'https',
    host: 'my.domain.com',
    pathPrefix: '/app',
  },
  techLists,
});

Rust

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      let tag = app
        .nfc()
        .scan(tauri_plugin_nfc::ScanRequest {
            kind: tauri_plugin_nfc::ScanKind::Ndef {
                mime_type: Some("text/plain".to_string()),
                uri: Some(tauri_plugin_nfc::UriFilter {
                  scheme: Some("https".to_string()),
                  host: Some("my.domain.com".to_string()),
                  path_prefix: Some("/app".to_string()),
                }),
                tech_list: Some(vec![
                  vec![tauri_plugin_nfc::TechKind::Ndef],
                ]),
            },
        })?
        .tag;
    }
    Ok(())
  })

Escribir en etiquetas NFC

La API write se puede utilizar para escribir una carga útil (payload) en una etiqueta NFC. Si no hay ninguna etiqueta escaneada con keepSessionAlive: true, la aplicación escaneará primero una etiqueta NFC.

JavaScript

import { write, textRecord, uriRecord } from '@tauri-apps/plugin-nfc';

const payload = [uriRecord('https://tauri.app'), textRecord('some payload')];

const options = {
  // the kind is only required if you do not have a scanned tag session alive
  // its format is the same as the argument provided to scan()
  kind: {
    type: 'ndef',
  },
  // configure the messages displayed in the "Scan NFC" dialog on iOS
  message: 'Scan a NFC tag',
  successfulReadMessage: 'NFC tag successfully scanned',
  successMessage: 'NFC tag successfully written',
};

await write(payload, options);

Rust

Precaución

Actualmente, la API de Rust solo proporciona una interfaz de bajo nivel para escribir cargas útiles (payloads) de NFC.

La API se mejoará pronto.

tauri::Builder::default()
  .setup(|app| {
    #[cfg(mobile)]
    {
      use tauri_plugin_nfc::NfcExt;

      app.handle().plugin(tauri_plugin_nfc::init());

      app
        .nfc()
        .write(vec![
          tauri_plugin_nfc::NfcRecord {
            format: tauri_plugin_nfc::NFCTypeNameFormat::NfcWellKnown,
            kind: vec![0x55], // URI record
            id: vec![],
            payload: vec![], // insert payload here
          }
        ])?;
    }
    Ok(())
  })

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

{
  "permissions": [
    ...,
    "nfc:default",
  ]
}

Permiso Predeterminado

Este conjunto de permisos configura qué tipo de operaciones están disponibles desde el plugin nfc.

Permisos Otorgados

Se permite comprobar si la funcionalidad NFC está disponible y escanear etiquetas cercanas. La escritura en etiquetas se debe habilitar manualmente.

Este conjunto de permisos predeterminado incluye lo siguiente:

• allow-is-available
• allow-scan

Tabla de Permisos

Identificador	Descripción
nfc:allow-is-available	Habilita el comando is_available sin ningún alcance preconfigurado.
nfc:deny-is-available	Deniega el comando is_available sin ningún alcance preconfigurado.
nfc:allow-scan	Habilita el comando scan sin ningún alcance preconfigurado.
nfc:deny-scan	Deniega el comando scan sin ningún alcance preconfigurado.
nfc:allow-write	Habilita el comando write sin ningún ámbito preconfigurado.
nfc:deny-write	Deniega el comando write sin ningún ámbito preconfigurado.