Linking and tagging information
The visitorId
provided by Fingerprint Pro 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.
Use case | Description |
---|---|
Account Takeover Prevention | Link visitor ID to account username to prevent malicious login attempts. Require multi-factor authentication if an unfamiliar visitor ID is trying to log in. |
Account Sharing Prevention | Link visitor ID to account username to prevent users from sharing accounts. Flag accounts that exceed a certain number of visitor IDs as suspected of account sharing. |
Trial Abuse Prevention | Link visitor ID to account username to prevent multiple sign-ups from a single visitor. Flag visitor IDs that exceed a certain number of associated accounts as suspected of trial abuse. |
Credit Card Fraud Prevention | Link visitor ID to hashed credit card numbers to prevent repeated use of faulty credit cards. Flag visitors that exceed a certain number of credit cards. |
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
ortag
parameters. Pass your metadata to Fingerprint Pro 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 Pro 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 Pro. See our Fingerprint Pro 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
linkedId
and tag
on the clientAssociate 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 Pro event for your own use.
What's the difference between linkedID
and tag
?
linkedID
and tag
?linkedId
is a simple string identifier. Fingerprint Pro indexes it so you can use it as a filter when retrieving the visit history of a specificvisitorId
via the Server API. Objects, arrays, or non-string values passed tolinkedId
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
SpoofingDefining
linkedId
andtag
in the browser is vulnerable to tampering, as is all client-side code. More sophisticated attackers can spoof thelinkedId
ortag
and send any arbitrary value to Fingerprint Pro API.We don't recommend relying on
linkedId
andtag
for security use cases. Link visitor IDs to other metadata on your server instead.
Data storageFingerprint Pro stores the visit history for a limited time (30 days for Pro accounts, 90 or more for Enterprise). After that, the fingerprinting events and their
linkedId
andtag
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 Pro 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 Pro, 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 Pro:
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.
Updated about 2 months ago