Instalación del Web SDK

Estado en producción y activación

La captura del Web SDK está desplegada en producción, en modo shadow (estado en producción). Su funcionamiento de extremo a extremo desde una página de cliente todavía se está midiendo; las primeras cifras de latencia de navegadores reales, en una aplicación, están en la página de captura. Prepare el frontend y el backend a la vez; la captura solo se acepta a través del dominio de captura activo de su aplicación, con el paquete aprobado y los datos emitidos. Un contexto no disponible se convierte en null; no debe interrumpir el inicio de sesión normal de su producto. Consulte la entrega de la implementación.

Sus datos de instalación verificados

• La clave pública de la aplicación (pub_app_…). Es un localizador, no un secreto.
• El dominio de captura activo, por ejemplo https://collect.yourcompany.com.
• La versión aprobada del paquete privado fingertrackid-sdk-web.tgz con sus digests SHA-256 y SHA-512. Descargue el paquete y vea ambos digests en la consola, con la sesión iniciada en su empresa: en Início, paso Configuração do SDK, o en Integração e saúde, tarjeta Pacote do SDK Web. Su rol debe tener permiso para leer la integración (administrador de la empresa, gestor de integración o auditor).

El SDK no está publicado en ningún registro npm público. No instale un paquete de un registro público solo porque su nombre coincida.

Instalación: paquete privado

Incluya el archivo aprobado en el bundle de su frontend. La consola muestra los digests que FingerTrackID registró para la versión aprobada; no los calcula a partir del archivo que usted recibió, y se niega a guardar una descarga que no coincida con el SHA-256. Aun así, verifique ambos digests en su propia máquina antes de instalar; un digest encontrado junto a un archivo que no es de confianza no es una aprobación. Si la consola indica que el paquete todavía no está disponible, póngase en contacto con el soporte de FingerTrackID.

Cada digest impreso debe ser igual al que muestra la consola. PowerShell imprime el digest en mayúsculas; compárelo sin distinguir mayúsculas de minúsculas. La consola ofrece los mismos comandos para copiar, para ambos sistemas. El paquete declara sus tipos de TypeScript.

Importe e inicialice en código del navegador, no durante el renderizado en el servidor. Cargue exactamente una copia; mantenga un único cliente para el documento actual del navegador y el ciclo de vida de la cuenta, en un módulo que sobreviva a los componentes de su página (la receta de captura lo hace). Haga commit del lockfile y mantenga el archivo aprobado en su proceso de dependencias. Al cerrar sesión o cambiar de cuenta, cierre este cliente y descarte sus handles de acción antes de inicializar otro.

Su bundler puede volver a minificar el paquete con su configuración de producción. Desde la 0.2.1, las comprobaciones de navegador del SDK siguen midiendo con opciones del minificador que tratan los métodos integrados como libres de efectos secundarios, como compress.unsafe de terser; con la 0.2.0, una compilación así las eliminaba (consulte las notas de la versión). Antes de publicar cada versión, se comprueba el paquete reminificado por terser y SWC con unsafe, unsafe_methods, pure_getters, passes: 3 y toplevel, y con las demás opciones unsafe_* que mantienen correcto el código ordinario.

Tres opciones de compresión reescriben la aritmética y las comprobaciones de tipo ordinarias. Según lo medido en el SDK 0.2.0, cada una por sí sola rompe el SDK: ya falla la apertura de la sesión, con TRANSPORT_ERROR o INVALID_RESPONSE, y ninguna captura llega a FingerTrackID. La misma medición en la 0.3.0 sigue pendiente. Manténgalas desactivadas para el paquete del SDK:

Minificador	Opción que rompe el SDK
terser	compress.unsafe_math, compress.booleans_as_integers
SWC	compress.unsafe_math, compress.unsafe_hoist_static_method_alias

Si su compilación activa alguna de ellas, excluya el paquete del SDK de esa minificación o desactive la opción y, a continuación, compruebe en el panel de red del navegador que la apertura de la sesión y la captura se completan.

macOS o Linux

shasum -a 256 fingertrackid-sdk-web.tgz
shasum -a 512 fingertrackid-sdk-web.tgz
npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz

Windows

Get-FileHash -Algorithm SHA256 .\fingertrackid-sdk-web.tgz
Get-FileHash -Algorithm SHA512 .\fingertrackid-sdk-web.tgz
npm install --save-exact --ignore-scripts ./fingertrackid-sdk-web.tgz

import { initializeSdk } from '@ftid/sdk-web'

let sdk = null
try {
  sdk = initializeSdk({
    publicKey: 'REPLACE_WITH_ISSUED_PUBLIC_APPLICATION_KEY',
    collectionOrigin: 'https://collect.customer.example',
  })
} catch {
  // Optional collection must not interrupt the customer's normal business action.
}

Sin instalación por script

El paquete privado incluido en el bundle de su frontend es la única forma de entrega. FingerTrackID no sirve el SDK como script: la distribución por script no está habilitada, y un origen de captura activo no aloja ningún archivo del SDK. No cargue el SDK desde una URL ni desde una CDN pública.

initializeSdk

• Recibe exactamente dos claves: publicKey (formato pub_app_…) y collectionOrigin (un origen HTTPS sin ruta, consulta, fragmento, credenciales ni puerto predeterminado explícito).
• Es síncrona y no hace ninguna solicitud de red.
• En la misma página, la misma configuración devuelve el mismo cliente mientras esté abierto; una configuración diferente lanza CONFIGURATION_CONFLICT.
• Una configuración no válida lanza INVALID_CONFIGURATION; un navegador sin las funciones requeridas lanza UNSUPPORTED_RUNTIME. Todas las demás llamadas del SDK informan los fallos en su resultado en lugar de lanzar excepciones, excepto createEvent (qué lanza).

El SDK requiere una página segura (HTTPS), Fetch, aleatoriedad criptográfica nativa y un reloj monotónico. Confirme la matriz de navegadores efectivamente calificada con su versión del SDK; las funciones del navegador por sí solas no son prueba de compatibilidad con todos los navegadores/versiones.

La CSP de su sitio

Añada el origen de captura activo exacto a su connect-src existente. El SDK se incluye en el bundle de su propio código, por lo que no necesita ninguna entrada en script-src.

Esto es un fragmento, no una CSP completa. El SDK no necesita unsafe-inline, unsafe-eval, comodines de host ni manejadores inline. Desde el SDK 0.1.1 no genera código en tiempo de ejecución, por lo que una CSP sin unsafe-eval no produce ningún informe de infracción por su causa. (El SDK 0.1.0 producía una infracción inofensiva de eval de script-src cuando su módulo se evaluaba por primera vez.) Las llamadas de su backend a la API de evaluación, https://api.fingertrackid.com, son de servidor a servidor y no van en esta lista del navegador; el navegador solo se comunica con su dominio de captura.

connect-src 'self' https://collect.customer.example;

Rastreo y otros encabezados de la solicitud

El dominio de captura acepta exactamente los encabezados de solicitud que envía el SDK: Content-Type, más X-Capability-Token en las solicitudes de captura y de contexto del evento, o X-SDK-Session-Token en la renovación y la terminación. El navegador anuncia cualquier otro encabezado en el preflight de CORS, y el dominio de captura rechaza ese preflight (400, sin aprobación de CORS). Entonces el navegador oculta la respuesta y la solicitud del SDK falla: cada llamada devuelve UNAVAILABLE con el motivo TRANSPORT_ERROR, y ninguna captura llega a FingerTrackID.

La instrumentación de la página que añade encabezados de rastreo a las solicitudes fetch salientes provoca exactamente esto cuando uno de sus patrones de URL también coincide con su origen de captura, por ejemplo un patrón para todos los subdominios de su dominio. Mantenga el origen de captura fuera de la propagación de trazas:

Herramienta	Opción	Qué comprobar
SDK de Sentry para navegador	tracePropagationTargets	Una entrada de tipo cadena coincide con cualquier URL que la contenga, por lo que 'yourcompany.com' también coincide con https://collect.yourcompany.com. Enumere los orígenes de su propia API con patrones anclados, como /^https:\/\/api\.yourcompany\.com\//
Datadog Browser RUM	allowedTracingUrls	Ninguna entrada, expresión regular ni función coincide con el origen de captura
OpenTelemetry FetchInstrumentation	propagateTraceHeaderCorsUrls	Ninguna entrada coincide con el origen de captura
Cualquier otro wrapper de fetch o cliente HTTP que añada encabezados	—	No añade nada a las solicitudes cuya URL empiece por su origen de captura

Para verificarlo, abra el panel de red del navegador en una página que capture: cada solicitud OPTIONS a su dominio de captura enumera en Access-Control-Request-Headers solo content-type (apertura de sesión) o content-type, x-capability-token (captura y contexto del evento), y se responde con 204.

Actualización del SDK

La captura de su aplicación acepta una sola versión del SDK a la vez, y una solicitud de otra versión se rechaza con AUTHENTICATION_FAILED. Instale la versión que ofrece la consola. Si su aplicación ya captura con una versión anterior, póngase en contacto con el soporte de FingerTrackID antes de desplegar un paquete nuevo: FingerTrackID pasa la aplicación a la nueva versión y usted despliega el paquete nuevo al mismo tiempo, porque a partir de ese momento la versión anterior se rechaza. Lo que cambió de la 0.1.1 a la 0.2.0 para su código está en la página de captura.

A partir de la 0.3.0, un número de versión designa un único paquete para siempre: un número publicado nunca vuelve con otro archivo. Cualquier cambio posterior, aunque sea de un solo byte, recibe un número nuevo: un patch cuando nada cambia en la API ni en el comportamiento, una versión minor (en 0.x) cuando se añade algo o algo se comporta de otra manera, con cada cambio incompatible enumerado a continuación. Cuando la consola ofrezca una versión nueva, lea sus notas de la versión antes de instalarla.

Notas de la versión

• 0.3.0.
  • Qué cambia. Una nueva exportación, createActionContextHelper(client, options?), con sus tipos (SdkActionContextHelper, SdkActionContext y los demás en la página de captura): ejecuta el ciclo de vida por usted, con prefetch() en la primera intención en un formulario, un take() por acción de negocio y close(). El reloj de credenciales del SDK ahora cuenta el tiempo que el dispositivo pasó en suspensión. Todas las exportaciones, tipos, solicitudes y temporizaciones de la 0.2.x siguen sin cambios.
  • Qué se rompe. Nada en la API. Tras una suspensión del dispositivo, el cliente deja de usar una credencial, una sesión o un token en caché que haya expirado durante la suspensión: un token en caché que haya superado su expiresAt responde EVENT_CONTEXT_EXPIRED, y la siguiente captura tras más de 30 minutos en suspensión abre una sesión nueva en lugar de reutilizar la anterior. La captura de su aplicación acepta una sola versión del SDK a la vez: una vez que FingerTrackID la pase a la 0.3.0, un navegador que todavía ejecute la 0.2.1 se rechaza con AUTHENTICATION_FAILED.
  • Migración. Póngase en contacto con el soporte para programar el cambio. Descargue la 0.3.0 desde la consola, verifique ambos digests e instálela con npm install --save-exact --ignore-scripts. El código de su página para la 0.2.x funciona sin cambios; se recomienda sustituirlo por la receta, y eso puede hacerse más adelante. Compile y prepare su frontend, y despliéguelo justo después de que FingerTrackID confirme el cambio. Luego inicie sesión una vez y compruebe que el inicio de sesión llegó a su backend con un token.
• 0.2.1. Nada cambia para su código: la API, el ciclo de vida, las solicitudes y la temporización son los de la 0.2.0. Corrige la 0.2.0 con bundlers que minifican el paquete con opciones que tratan los métodos integrados como libres de efectos secundarios (por ejemplo, compress.unsafe de terser): en una compilación así, la 0.2.0 perdía sus comprobaciones del motor de JavaScript, por lo que las señales de privacidad del navegador y de ventana privada de cada acceso volvían como no evaluadas. La 0.2.1 hace que sigan midiendo con terser y SWC con esas opciones. Si su aplicación captura con la 0.2.0, póngase en contacto con el soporte para pasarla a la 0.2.1 como se describe arriba.
• 0.2.0. prepare(), una nueva sesión del SDK para cada nueva captura, plazos del cliente por encima de los presupuestos del servidor con reintentos dentro de la misma llamada, y reutilización del preflight de CORS. Lo que cambia para su código está en la página de captura.

Siguiente paso: capture y obtenga el contexto del evento.