Options

You can pass your options to Thumbmark when instantiating the Thumbmark class, like so:

const t = new Thumbmark({ api_key: 'xxxxxxxxxxx', exclude: ['permissions'], timeout: 7000 })

The ThumbmarkJS GitHub page will have the most up-to-date information of the available options.

API key

The API key is not mandatory. However, providing a valid API key allows ThumbmarkJS to utilize server-side fingerprinting components, which significantly improve the uniqueness of the resulting identifier.

You can obtain a free API key from the ThumbmarkJS console.

A free API key gives you 1,000 API requests per month.

Provide the API key like so:

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

Include

include is a way to only include listed fingerprinting components. include is only applied to client components, not server-side components.

include takes a list of strings. You can provide a top-level component name in include such as ['canvas', 'audio']. You can also use dot-separation to pick not the whole component, but pieces of the component, like ['system.browser.name', 'webgl']. This would pick the whole webgl component, and the browser name from system, nothing else.

Usage:

const t = new Thumbmark({ include: ['canvas', 'audio', 'webgl'] })

Exclude

exclude works similarly to include but excludes the listed components. It also only applies to client components.

Usage:

const t = new Thumbmark({ exclude: ['permissions'] })

Timeout

There is a default timeout for calculating the fingerprinting components of 5,000 milliseconds. This is plenty typically, as it should not take even near this long to calculate the fingerprint. However, if you need to adjust this, you can do so as follows:

Usage:

const t = new Thumbmark({ timeout: 7000 })

The same timeout is also applied to the API call when an API key is set.

Stabilize

Choosing what situations to stabilize the thumbmark fingerprint for is a trade-off between uniqueness and stability. For example, normal browsing allows for much more details to be captured for the fingerprint, which might be useful in some situations.

stabilize is a set of predefined settings that thumbmark can be configured to stabilize for. For example, stabilizing for private means components that can differ between normal and private browsing will be excluded.

stabilize takes a list of strings. The currently supported keys are:

Key	What it stabilizes for
private	Differences between normal and private/incognito browsing across Firefox, Safari, Chrome, Edge, Brave and Samsung Browser
iframe	Differences when ThumbmarkJS runs inside an iframe (mostly Safari-specific)
vpn	Network-derived signals such as ip
always	Components that are always unstable on certain browsers (e.g. speech on Brave/Firefox)

The default value is ['private', 'iframe'].

Usage:

const t = new Thumbmark({ stabilize: ['private', 'iframe', 'vpn'] })

The exact rules can be inspected at runtime via the exported stabilizationExclusionRules constant.

Logging

Logging is enabled by default, but with this option it can be disabled.

When logging is enabled, ThumbmarkJS randomly logs the components for ~0.01% of calculated thumbmarks. This sampled data is used for analysis purposes in order to improve the free ThumbmarkJS fingerprinting library.

To disable logging:

const t = new Thumbmark({ logging: false })

Property name factory

By default, ThumbmarkJS stores the thumbmark in local storage with the key thumbmark_visitor_id. If you need to customize this, you can do this by using the property_name_factory option. This is documented in the Local Storage property names section.

The previous storage_property_name option is deprecated — use property_name_factory instead.

API endpoint

By default, ThumbmarkJS uses the API endpoint https://api.thumbmarkjs.com. If you need to customize this, you can do so as follows:

const t = new Thumbmark({
    api_key: 'xxxxxxxxxxx',
    api_endpoint: 'https://api.thumbmarkjs.com'
    })

NOTE:

• This only has an effect if you are using the API key.
• This is meant for Enterprise customers, as setting this up requires co-ordination with ThumbmarkJS.

Cache lifetime

⚠️ use caching at your own risk ⚠️

Setting cache_lifetime_in_ms to a value greater than 0 will enable caching of the API response in localStorage. The default is 0 (disabled), and the maximum is 259_200_000 (72 hours).

More on caching can be found in the Caching section.

The previous cache_api_call boolean is deprecated and will be removed in 2.0 — set cache_lifetime_in_ms instead.

Performance

If performance is a topic for you, you can expose the amount of milliseconds each component takes to resolve by setting performance to true. The timings are returned on ThumbmarkResponse.elapsed.

const t = new Thumbmark({ performance: true })

Experimental components

Setting experimental to true resolves additional components that are still under evaluation (intl, mathml, mediadevices) and exposes them on ThumbmarkResponse.experimental. They are not included in the thumbmark hash.

const t = new Thumbmark({ experimental: true })

See the Experimental components page for the current list.

Permissions to check

The permissions component queries a default list of Permission API names. You can override the list with permissions_to_check:

const t = new Thumbmark({
    permissions_to_check: ['geolocation', 'notifications', 'camera'],
})

Metadata

If you want to correlate fingerprinting results with something on your side — a user ID, an order reference, an A/B test bucket — pass it via metadata. The value is forwarded to the API and echoed back in the response (and in any webhook deliveries) on the metadata field.

metadata accepts a JSON value (string, number, boolean, array or object) or a function returning a JSON value. Functions are evaluated at request time, which is useful when the value depends on app state at the moment of the call.

// Static
const t = new Thumbmark({
    api_key: 'xxxxxxxxxxx',
    metadata: { userId: 'abc123', source: 'checkout' },
})

// Dynamic
const t = new Thumbmark({
    api_key: 'xxxxxxxxxxx',
    metadata: () => ({ timestamp: Date.now(), sessionId: getSessionId() }),
})

NOTE:

• metadata is excluded from fingerprint calculation — it does not affect the resulting thumbmark or visitorId.
• The stringified value must be ≤ 1000 characters. Larger payloads are dropped with a console error.
• Only effective when an API key is configured (it is sent on the API request).

Keep in mind though that Thumbmark normally makes just a single API call during its lifetime, so if you need more than that, and you can't find out how to do it, reach out to us.