Basic usage

Identifiers

ThumbmarkJS provides two different identifiers, and understanding their difference is important.

The free open source library only provides the thumbmark, which is a hash calculated from technical components of the browser.

When you use the API version by providing an API key to Thumbmark, you are also given a visitorId. The visitorId is significantly more unique than the thumbmark alone, because the API also takes into account server-side signals (HTTP headers, TLS handshake, IP-derived data, …) and runs additional reconciliation. You should be using visitorId whenever you have an API key.

Import and set up

Once you have imported ThumbmarkJS, you need to access the Thumbmark constructor, and optionally pass the options, e.g. api_key if you have one.

const t = new Thumbmark({ api_key: 'xxxxxxxxxxxx' });

Getting your identifiers

Once you have your instance of Thumbmark class, you can run the get() method to generate your identifiers and all the other data.

const tm_data = await t.get();

⚠️ This operation needs to be run in a browser context. For example, if you are developing a Next.js / React app, ensure you run this in the client side and use useEffect.

Return value

get() resolves with an object that has the following shape:

{
    thumbmark: string;          // The digital fingerprint hash
    visitorId?: string;         // Persistent visitor identifier (only when API key is set)
    components: {...};          // The components used to calculate thumbmark
    info: {...};                // Smart signals from the API: ip_address, classification, uniqueness
    version: string;            // The version of ThumbmarkJS used. Keep this up to date.

    // Present conditionally:
    elapsed?: Record<string, number>;  // Per-component timings — only when options.performance is true
    experimental?: {...};              // Experimental components — only when options.experimental is true
    requestId?: string;                // API request id, useful for support
    metadata?: string | object;        // Metadata you passed in, echoed back from the API
    error?: ThumbmarkError[];          // Structured error array, present only when something went wrong
}

Errors

ThumbmarkJS does not throw from get(). Component failures, API failures and timeouts are surfaced as a structured error array on the response. Each entry has a type and a message, and component-level errors also include a component name. The possible types are:

type	When
component_timeout	A single component did not resolve before options.timeout
component_error	A single component threw
api_timeout	The API call timed out
api_error	The API returned an HTTP error
api_unauthorized	API key invalid, origin not allowed, or quota exceeded (HTTP 403). In this case thumbmark, components, info and visitorId are all empty/undefined.
network_error	The API call failed due to a network failure (after retries)
fatal	A non-recoverable error, including running outside a browser environment

You can therefore have a partial result — e.g. a valid thumbmark with one or two components missing because they timed out. The shape is:

{
    thumbmark: 'xxxx',
    components: { ... },
    info: { ... },
    version: '1.7.7',
    error: [
        { type: 'component_timeout', message: "Component 'webrtc' timed out", component: 'webrtc' },
    ],
}