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 three ways to link visitor IDs with your own metadata:

• On your server, in your own database: Process visitor ID and metadata on your server and store them in your own database table. This approach is secure, durable, and recommended for most security use cases.
• On your client, during the identification event: Use the linkedId or tag parameters to pass your metadata to the Fingerprint API when requesting the visitor ID. Fingerprint stores this data for 30 or 90+ days, depending on your plan. This method is recommended for use cases where spoofing and long-term storage are not a concern.
• On your server, after the identification event: Update existing events by sending the linkedId or tag information to the /events endpoint with a PUT request. This method allows for modifying event data after the initial identification, which is useful if the information was not available at the time of the client-side request. The updated data is stored the same way as the client-side parameters.

Linking information in your own database

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"
    ]
  },
}

Updating linkedId and tag on the server

Associate linkedId or tag data with a visitorId using the /events endpoint of the Fingerprint Server API with a PUT request.

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

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

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

fpPromise
  .then((fp) => fp.get())
  .then((result) => {
    const { requestId } = result;

    // Send information to the server for processing the order
    // At this point, we do not have the order ID yet
    fetch(`/api/process-order`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({
        requestId,
        // Any other relevant information related to the order process can be sent here. e.g., cart ID, products, etc.
      }),
    });
  });

On the backend, use the requestId to make a PUT request to the /events endpoint of the Fingerprint Server API.

const response = await fetch(`https://api.fpjs.io/events/${requestId}`, {
  method: "PUT",
  headers: {
    "Content-Type": "application/json",
    "Auth-API-Key": SECRET_API_KEY,
  },
  body: JSON.stringify({
    linkedId: orderId, // Use the order ID as the linkedId
    tags: {
      orderStatus: "completed", // Example additional tag
      paymentMethod: "credit_card", // Example additional tag
    },
  }),
});

Your information will be added to the event and available through the Dashboard and Server API.

{
  "visitorId": "cxhbePz123zrMpABC2r3",
  "requestId": "1730134629123.MALXYZ",
	// ...
  "linkedId": "orderNum12345",
  "tag": {
    "orderStatus": "completed",
    "paymentMethod": "credit_card"
  },
}

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.