Linking and tagging information

The visitorId provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. You can follow user actions, track logged-in devices, and recognize malicious behavior.

There are two ways to link visitor IDs with your own metadata:

• On your server: Process visitor ID and metadata on your server and store them in your own database table. Secure, durable, and recommended for most security use cases.
• On your client, using linkedId or tag parameters. Pass your metadata to Fingerprint API when requesting the visitor ID. Fingerprint stores the data for 30 or 90+ days depending on your plan. Recommended for use cases where spoofing and long-term storage are not a concern.

Linking information on the server

On the client, use the Fingerprint JS Agent to get a visitorId and send it to your server for processing.

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro';

// ...
const fpPromise = FingerprintJS.load({ apiKey: PUBLIC_API_KEY });

fpPromise
  .then((fp) => fp.get())
  .then((result) => {
    const { visitorId, requestId } = result;
    fetch(`/api/linking-data`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        visitorId,
        requestId,
        accountId: '123456',
      }),
    });
  });

Inside the server endpoint, verify the authenticity of the visitorId and save it to your database together with your internal ID or other metadata.

export default async function submitEndpointHandler(req, res) {
  const { requestId, visitorId, accountId } = req.body;
  if (!areIDsValid(requestId, visitorId)) {
    res.status(400).send('Something went wrong.');
    return;
  }
  saveToAccountsDatabaseTable({
    visitorId, 
    accountId
  });
  res.status(200).send('visitorId and accountId link saved to database');
}

📘

Verifying the visitorId involves calling our Server API to make sure it was recently generated by Fingerprint. See our Fingerprint Use Cases project for implementation examples.

This approach requires more setup but is more secure. You have full control over the data and can store it indefinitely.

Using linkedId and tag on the client

Associate your data with a visitorId using the linkedId or tag parameter of the JS agent's get() function.

<script>
  const fpPromise = import('https://fpjscdn.net/v3/<your-public-api-key>')
    .then(FingerprintJS => FingerprintJS.load());

  // Pass your own data to get()
  fpPromise
    .then(fp => fp.get({
      linkedId: "accountNum12345",
      tag: {
        orders: ["orderNum6789"],
      	location: { city: "Atlanta", country: "US" }
      } 
  	}))
    .then(result => console.log(result.visitorId));
</script>

Your information will be part of that fingerprinting event and available through Webhooks and Server API. You can use webhooks to automatically store the events in your own database indefinitely.

{
  "visitorId": "cMBjS1eCyObMgQ4BiYEO",
  "requestId": "1680110819553.B2U183",
	// ...
  "linkedId": "accountNum12345",
  "tag": {
    "location": {
      "city": "Atlanta",
      "country": "US"
    },
    "orders": [
      "orderNum6789"
    ]
  },
}

Tagged or linked information has no influence on identification accuracy. Both tag and linkedId are arbitrary pieces of information linked to a particular Fingerprint event for your own use.

What's the difference between linkedID and tag?

• linkedId is a simple string identifier. Fingerprint indexes it so you can use it as a filter when retrieving the visit history of a specific visitorId via the Server API. Objects, arrays, or non-string values passed to linkedId are converted to strings.
• tag accepts any simple value or any JavaScript object smaller than 16KB. It cannot be used to filter visits but can store a large amount of structured data about your visitor.

🚧

Limitations

Spoofing

Defining linkedId and tag in the browser is vulnerable to tampering, as is all client-side code. More sophisticated attackers can spoof the linkedId or tag and send any arbitrary value to Fingerprint API.

We don't recommend relying on linkedId and tag for security use cases. Link visitor IDs to other metadata on your server instead.

Data storage

Fingerprint stores the visit history for a limited time (30 days for accounts, 90 or more for Enterprise). After that, the fingerprinting events and their linkedId and tag values will not be available through the Server API.

If your use case requires long-term data storage, you can use webhooks to store the events in your database as they happen or link visitor IDs to your metadata on your server entirely.

Hashing linked or tagged information

Fingerprint Identification is often useful when your internal IDs are unavailable, for example, on a login or signup page. To avoid sending emails, phone numbers, or other sensitive information to Fingerprint, you can hash the information first and pass only the hash into thetag or linkedId.

📘

Hashing explained

A hash function is a mathematical function that takes an input of arbitraty length and outputs a random-looking fixed-length representation of it. Hash functions are used to represent the original data in a more efficient and secure way.

• For the same input, a hash function always returns the same result.
• Any change in input leads to a different result (collisions are rare).
• Computing the original input from its hash is practically impossible.

You can use the crypto browser API to hash sensitive information before sending it to Fingerprint:

async function hash(sensitiveInfo) {
  hashBytes = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(sensitiveInfo));
  return Array.prototype.map
    .call(new Uint8Array(hashBytes), (byte) => byte.toString(16).padStart(2, '0'))
    .join('');
}

const email = "[email protected]";
const linkedId = await hash(email);
// linkedId is now '9663a85cfcd473cba225ab15bbb4ca6a424203297f62e87abd5fa897a6f0aef7'

fpPromise
  .then(fp => fp.get({ linkedId	}))
  .then(result => console.log(result.visitorId));

For example, you might want to reduce multiple signups from the same visitor ID. On submit, you can use the Server API to retrieve all email hashes recently linked to that visitor ID. Then flag or block the visitor ID if it exceeds a certain number of linked emails.