ThumbmarkJS is now the world's best free browser fingerprinting JavaScript library. It is used to generate over a billion thumbmarks every month.
The client ThumbmarkJS library is open source (MIT). There also an API version. Learn more at ThumbmarkJS website.
ThumbmarkJS is meant to be used for good. Use this to prevent scammers and spammers for example. If you see this library being used for evil, contact me.
🕺 Join the Thumbmark Discord channel
Have a look at the IOS and Android versions as well.
Even the client library alone works adequately to distinguish common browsers. Sampled data show a uniqueness of 90%-95%.
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. Like 99%.
Transpiled bundles are available now 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
<script src="https://cdn.jsdelivr.net/npm/@thumbmarkjs/thumbmarkjs/dist/thumbmark.umd.js"></script>
<script>
const tm = new ThumbmarkJS.Thumbmark();
tm.get().then((res) => {
console.log(res)
})
</script>
<!-- or -->
<script>
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)
})
})
</script>Options are passed to the Thumbmark constructor 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 |
| 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. |
| cache_api_call | boolean | false | Default is false. If using the API, this caches the API response for the current page load. |
| performance | boolean | false | Default is false. Setting to true includes millisecond performance of component resolving |
example usage:
const tm_api = new ThumbmarkJS.Thumbmark({
api_key: 'ae8679607bf79faefe3373ec1a8305863abd6abf2dd94ecbf300fd25b8da7495',
exclude: ['math']
});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). So for example, if you wanted to include an IP address in the components, you could do it like so:
function fetchIpAddress() {
return new Promise((resolve, reject) => {
fetch('http://checkip.amazonaws.com')
.then(response => {
if (!response.ok) {
throw new Error('Network response was not ok');
}
return response.text();
})
.then(ip => resolve({'ip_address': ip.trim()}))
.catch(error => {
console.error('There was a problem with the fetch operation:', error);
reject(error);
});
});
}
const tm = new ThumbmarkJS.Thumbmark();
tm.includeComponent('ip_address', fetchIpAddress)The function is expected to return a Promise, but it seems it works without, too.
Installing from NPM:
npm install @thumbmarkjs/thumbmarkjsand in your code
import { Thumbmark } from '@thumbmarkjs/thumbmarkjs'To implement ThumbmarkJS in a Next.js app, you can use a component like this.
Clone this repo and then run
npm run install
npm run build
- 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
- and a bunch of smaller things
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