Pro components

When you use an API key, ThumbmarkJS makes a call to the backend in addition to running the local components. The backend has access to information the browser cannot see — most importantly, HTTP headers and their order, the IP address, and how the client performs the TLS handshake — and uses those to reconcile and stabilise the visitor identity.

The result is two things that are returned alongside the regular thumbmark:

visitorId

A persistent visitor identifier. This is what you should use as the primary identifier when you have an API key — it is significantly more stable and significantly more unique than the open-source thumbmark alone.

const { visitorId } = await t.get();

info

A bundle of "smart signals" derived server-side. The shape is:

info: {
    ip_address?: {
        ip_address: string;
        ip_identifier: string;
        autonomous_system_number: number;
        ip_version: 'v4' | 'v6';
    };
    classification?: {
        tor: boolean;
        vpn: boolean;
        bot: boolean;
        datacenter: boolean;
        danger_level: number; // 0 (safe) to 5 (block)
    };
    uniqueness?: {
        score: number | string;
    };
}

classification.danger_level is a quick way to gate risky traffic — 0 is no detected risk, 5 is the highest and is what you'd typically block.

info is also returned in webhook deliveries, so you can do the same gating server-side without having to trust the client.