Caching visitor information

Fingerprint usage is billed per API call. There are two main ways to avoid unnecessary API calls depending on your use case:

Just-in-time visitor identification

Identify visitors on demand only when necessary, just before you need their visitor ID. For example, to prevent account takeover, you can install the Fingerprint client agent only on your login page and get the visitor ID just before logging the user in. We recommend always using a fresh visitor ID for sensitive actions and security use cases, to minimize the potential for replay attacks.

Caching the visitor ID

Your use case might require knowing the visitor ID at all times, for example, content personalization. There is usually no need to re-identify the visitor repeatedly on every page load as they navigate your website. To avoid unnecessary API calls, you can cache identification results.

Caching using Fingerprint client libraries

The easiest way to cache visitor information is to install Fingerprint using one of our open-source client libraries. All of them provide caching out of the box:

• Angular
• React, Preact, Next.js
• Svelte
• Vue
• Generic JS Agent Wrapper for SPAs

By default, our libraries use sessionStorage to cache results but you can specify a different cache location:

• sessionStorage (default) — cleared when the page session ends (closing the browser tab or window).
• localStorage — persists even when the browser is closed and reopened, cleared manually by the user.
• memory — cleared on page reload.
• noCache — disable caching completely if needed.

You can also provide your own custom cache implementation to the library. By default, the cache time limit is 1 hour, and the maximum possible cache time is 24 hours. Please refer to the documentation of your chosen library on GitHub for more details.

📘

A note on Incognito mode

Values stored in sessionStorage, localStorage, and cookies are not available from Incognito mode, so these caching attempts will not work if a visitor switches from normal to private browsing (or vice versa).

Custom cache

If you are not using one of our libraries, you can implement your own caching using sessionStorage, localStorage, or client-side cookies. The general principle is always the same:

1. Check if your cache storage contains a visitorId and its timestamp is within your cache time limit. If yes, use the visitor ID.
2. If not, use the JavaScript agent to make an identification request to the Fingerprint API.
3. Save the returned visitorId to your cache storage along with a timestamp.

Caching time limit

For most use cases, caching visitor IDs for 1 hour is sufficient to avoid over-utilization without affecting identification accuracy. Generally, we recommend always keeping the cache time limit shorter than 24 hours:

• Maintains high identification accuracy.
• Keeps the information from Smart signals up to date.
• Reduces the risk of replay attacks — malicious actors reusing a cached ID and abusing it for the duration of the cache.

📘

Explanation: Why does over-caching lead to lower accuracy?

Browsers naturally go through incremental changes as users install updates, add extensions, plug in external monitors, or change internet connections. Fingerprint continually captures these incremental changes a few at a time and recognizes moderately updated browser configurations as the same browser using the other stable signals.

However, long delays between identification events can increase the risk that the two browser configurations are too different to safely assign them the same visitor ID. Do not cache visitor IDs for longer than 24 hours to avoid unnecessary false negatives.