Installing the Web SDK

Production status and activation

Web SDK collection is deployed in production, in shadow mode (production status). Its end-to-end operation from a customer page is still being measured; the first latency figures from real browsers, on one application, are on the collection page. Prepare the frontend and backend together; collection is accepted only through your application’s active collection domain, with the approved package and issued inputs. An unavailable context becomes null; it must not interrupt your product’s normal login. See the implementation handoff.

Your verified installation inputs

• The application public key (pub_app_…). It is a locator, not a secret.
• The active collection domain, for example https://collect.yourcompany.com.
• The approved version of the private fingertrackid-sdk-web.tgz package with its SHA-256 and SHA-512 digests. Download the package and see both digests in the dash, signed in to your company: in Início, step Configuração do SDK, or in Integração e saúde, card Pacote do SDK Web. Your role must be allowed to read the integration (company administrator, integration manager or auditor).

The SDK is not published to any public npm registry. Do not install a package from a public registry just because its name matches.

Installation: private package

Bundle the approved archive into your frontend. The dash shows the digests FingerTrackID recorded for the approved release; it does not compute them from the file you received, and it refuses to save a download that does not match the SHA-256. Still verify both digests on your own machine before installing; a digest found beside an untrusted archive is not approval. If the dash says the package is not available yet, contact FingerTrackID support.

Each printed digest must equal the one shown in the dash. PowerShell prints the digest in uppercase; compare it without regard to case. The dash offers the same commands to copy, for both systems. The package declares its TypeScript types.

Import and initialize in browser code, not during server-side rendering. Load exactly one copy; keep one client for the current browser document and account lifecycle, in a module that outlives your page components (the collection recipe does this). Commit the lockfile and keep the approved archive in your dependency process. On logout or account switch, close this client and discard its action handles before initializing another.

Your bundler may minify the package again with your production settings. Since 0.2.1 the SDK’s browser checks keep measuring under minifier options that treat built-in methods as free of side effects, such as terser’s compress.unsafe; with 0.2.0 such a build removed them (see the release notes). Before each release the package is checked re-minified by terser and SWC with unsafe, unsafe_methods, pure_getters, passes: 3 and toplevel, and with the other unsafe_* options that keep ordinary code sound.

Three compression options rewrite ordinary arithmetic and type checks. Measured on SDK 0.2.0, each one on its own breaks the SDK: the session open already fails, with TRANSPORT_ERROR or INVALID_RESPONSE, and no collection reaches FingerTrackID. The same measurement on 0.3.0 is still pending. Keep them off for the SDK package:

Minifier	Option that breaks the SDK
terser	compress.unsafe_math, compress.booleans_as_integers
SWC	compress.unsafe_math, compress.unsafe_hoist_static_method_alias

If your build turns one of them on, exclude the SDK package from that minification or turn the option off, then check in the browser’s network panel that the session open and the collection complete.

macOS or 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.
}

No script installation

The private package bundled into your frontend is the only delivery. FingerTrackID does not serve the SDK as a script: script distribution is not enabled, and an active collection origin hosts no SDK file. Do not load the SDK from a URL or a public CDN.

initializeSdk

• Takes exactly two keys: publicKey (format pub_app_…) and collectionOrigin (an HTTPS origin with no path, query, fragment, credentials or explicit default port).
• It is synchronous and makes no network request.
• On the same page, the same configuration returns the same client while it is open; a different configuration throws CONFIGURATION_CONFLICT.
• An invalid configuration throws INVALID_CONFIGURATION; a browser without the required features throws UNSUPPORTED_RUNTIME. Every other SDK call reports failures in its result instead of throwing, except createEvent (what throws).

The SDK requires a secure page (HTTPS), Fetch, native cryptographic randomness and a monotonic clock. Confirm the actually qualified browser matrix with your SDK release; browser features alone are not evidence of compatibility with every browser/version.

Your site’s CSP

Add the exact active collection origin to your existing connect-src. The SDK is bundled into your own code, so it needs no script-src entry.

This is a fragment, not a complete CSP. The SDK does not need unsafe-inline, unsafe-eval, host wildcards or inline handlers. Since SDK 0.1.1 it generates no code at run time, so a CSP without unsafe-eval produces no violation report from it. (SDK 0.1.0 produced one harmless script-src eval violation when its module was first evaluated.) Your backend’s calls to the assessment API, https://api.fingertrackid.com, are server-to-server and do not go in this browser list; the browser only talks to your collection domain.

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

Tracing and other request headers

The collection domain accepts exactly the request headers the SDK sends: Content-Type, plus X-Capability-Token on collection and event-context requests or X-SDK-Session-Token on renewal and termination. The browser announces any other header in the CORS preflight, and the collection domain refuses that preflight (400, without CORS approval). The browser then hides the answer and the SDK request fails: every call returns UNAVAILABLE with reason TRANSPORT_ERROR, and no collection reaches FingerTrackID.

Page instrumentation that adds tracing headers to outgoing fetch requests causes exactly this when one of its URL patterns also matches your collection origin, for example a pattern for every subdomain of your domain. Keep the collection origin out of trace propagation:

Tool	Option	What to check
Sentry browser SDKs	tracePropagationTargets	A string entry matches any URL that contains it, so 'yourcompany.com' also matches https://collect.yourcompany.com. List your own API origins with anchored patterns, such as /^https:\/\/api\.yourcompany\.com\//
Datadog Browser RUM	allowedTracingUrls	No entry, regular expression or function matches the collection origin
OpenTelemetry FetchInstrumentation	propagateTraceHeaderCorsUrls	No entry matches the collection origin
Any other fetch wrapper or HTTP client that adds headers	—	It adds nothing to requests whose URL starts with your collection origin

To verify, open the browser’s network panel on a page that collects: each OPTIONS request to your collection domain lists in Access-Control-Request-Headers only content-type (session open) or content-type, x-capability-token (collection and event context), and is answered with 204.

Upgrading the SDK

Your application’s collection accepts one SDK version at a time, and a request from another version is refused with AUTHENTICATION_FAILED. Install the version the dash offers. If your application already collects with an earlier version, contact FingerTrackID support before you deploy a new package: FingerTrackID moves the application to the new version and you deploy the new package at the same time, because from then on the earlier version is refused. What changed from 0.1.1 to 0.2.0 for your code is on the collection page.

From 0.3.0 on, a version number names one package forever: a released number never comes back with another file. Any later change, even a single byte, gets a new number: a patch when nothing in the API or the behavior changes, a minor version (in 0.x) when something is added or behaves differently, with every breaking item listed below. When the dash offers a new version, read its release notes before you install it.

Release notes

• 0.3.0.
  • What changes. A new export, createActionContextHelper(client, options?), with its types (SdkActionContextHelper, SdkActionContext and the others on the collection page): it runs the lifecycle for you, with prefetch() on the first intent of a form, one take() per business action and close(). The SDK’s credential clock now counts the time the device spent asleep. Every 0.2.x export, type, request and timing is unchanged.
  • What breaks. No API. After the device sleeps, the client stops using a credential, a session or a cached token that expired during the sleep: a cached token past its expiresAt answers EVENT_CONTEXT_EXPIRED, and the next collection after more than 30 minutes asleep opens a new session instead of reusing the old one. Your application’s collection accepts one SDK version at a time: once FingerTrackID moves it to 0.3.0, a browser still running 0.2.1 is refused with AUTHENTICATION_FAILED.
  • Migration. Contact support to schedule the move. Download 0.3.0 from the dash, verify both digests and install it with npm install --save-exact --ignore-scripts. Your 0.2.x page code runs unchanged; replacing it with the recipe is recommended and can come later. Build and stage your frontend, and deploy it right after FingerTrackID confirms the move. Then sign in once and check that the login reached your backend with a token.
• 0.2.1. Nothing changes for your code: the API, the lifecycle, the requests and the timing are those of 0.2.0. It fixes 0.2.0 under bundlers that minify the package with options that treat built-in methods as free of side effects (for example terser’s compress.unsafe): in such a build 0.2.0 lost its JavaScript-engine checks, so the browser privacy and private-window signals of every access came back as not evaluated. 0.2.1 keeps them measuring under terser and SWC with those options. If your application collects with 0.2.0, contact support to move it to 0.2.1 as described above.
• 0.2.0. prepare(), a new SDK session for each new collection, client deadlines above the server budgets with retries inside the same call, and reuse of the CORS preflight. What it changes for your code is on the collection page.

Next step: collect and obtain the event context.