@thumbmarkjs/thumbmarkjs

ThumbmarkJS

ThumbmarkJS is now the world's best free browser fingerprinting JavaScript library. It is used to generate over a billion thumbmarks every month. Use this to prevent scammers and spammers for example. If you see this library being used for evil, contact me.

🆓 The client ThumbmarkJS library is open source (MIT). The free open source library provides the best-in-class free browser fingerprinting technology and can be used also commercially.

🆒 There also an enhanced API version. Learn more at thumbmarkjs.com.

The API version:

• Produces significantly more unique fingerprints by adding server-side components
• Adds smart signals such as bot, vpn, tor & datacenter traffic detection, and also threat level
• Provides uniqueness scoring

🕺 Join the ThumbmarkJS Discord channel to discuss

How well does it perform?

Even the client library alone works adequately to distinguish common browsers. Sampled data show a uniqueness of around 80%.

Mileage may vary though. Mac/Safari users tend to either clash more than Windows users, or be too unique (noise in the components). It does depend on your audience, too.

With the added entropy from an API call, that includes server-side components by investigating headers, TLS handshake signatures etc, it gets veeery unique. Over 99%. The visitor ID further improves both uniqueness and especially stability. Detailed statistics coming.

Documentation : docs.thumbmarkjs.com

This GitHub repository provides the very basic information on usage and installation. The web documentation is more thorough.

Import from jsDelivr

Do check the documentation for how to install and use ThumbmarkJS whether it is by importing from CDN or installing from NPM.

Transpiled bundles are available on JSDelivr.

Supported module formats:

• UMD: https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.umd.js
• CommonJS: https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.cjs.js
• ESM: https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.esm.js

You can run this in developer console for example as a test:

import('https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.umd.js')
.then(() => {
  const tm = new ThumbmarkJS.Thumbmark();
  tm.get().then((res) => {
      console.log(res)
  })
})

Install with NPM

‼️ Please refer to the documentation

However, you get it from NPM:

npm install @thumbmarkjs/thumbmarkjs

:warning: the fingerprinting needs to run in a browser context. Let me know if the library fails on a server side import, that shouldn't happen. To calculate the components though, it needs the browser APIs.

Integrations (React, Vue)

React and Vue integration plugins are being worked on, have a look.

Options are... optional

Thorough documentation about options are at docs.thumbmarkjs.com.

Options are passed to the Thumbmark class constructor, like so:

const tm = new ThumbmarkJS.Thumbmark({
  option_key: option_value
})

option	type	example	what it does
api_key	string	'ae8679607bf79f......'	Setting this to a key you've obtained from https://thumbmarkjs.com makes thumbmarks incredibly more unique and enables visitorId
exclude	string[]	['webgl', 'system.browser.version']	Removes components from the fingerprint hash. An excluded top-level component improves performance.
include	string[]	['webgl', 'system.browser.version']	Only includes the listed components. exclude still excludes included components.
permissions_to_check	string[]	['gyroscope', 'accelerometer']	Checks only selected permissions. Like 'include', but more low-level. Permissions take the longest to resolve, so this is if you need to cut down some milliseconds.
timeout	integer	5000	Default is 5000. Component timeout in milliseconds.
logging	boolean	true	Default is true. Some releases collect at most 0.01% logs to improve the library. This doesn't affect the user.
performance	boolean	false	Default is false. Setting to true includes millisecond performance of component resolving
stabilize	string[]	['private', 'iframe']	A preset exclusion list for different scenarios. Default is ['private', 'iframe'] which means thumbmark uses settings designed to stabilize for private browsing and iframes (i.e. thumbmark should be stable over those situations).

example usage:

const tm_api = new ThumbmarkJS.Thumbmark({
    api_key: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    exclude: ['math']
});

Custom components

You can add custom components to the hash with includeComponent, which takes two parameters, the key being the key of the component in the JSON and the function that returns the value (a string, a number or a JSON object). Custom components are described in here in the documentation.

Components included in fingerprint

• audio fingerprint
• canvas fingerprint
• webgl fingerprint
• available fonts and how they render
• videocard
• browser languages and time zone
• browser permissions
• available plugins
• a ton of screen details including media queries
• TLS handshake details (API only)
• HTTP headers (API only)
• Connection/IP details (API only)

Technical details

I wanted to create something that's easy to build, extend and use. If you're interested in how the library works, the structure is very simple.

Have a look at the technical_details

Contact ThumbmarkJS

• email: [e-mail]

• discord: https://discord.gg/PAqxQ3TnDA