Guides
Sign Up
Start typing to search…

Optimize JavaScript agent usage

A collection of techniques to optimize your usage of the JavaScript agent. With a few adjustments, you can reduce latency and decrease the number of API calls required for your use case.

The JavaScript agent is a client-side JavaScript SDK that collects browser attributes and sends them to Fingerprint servers for processing and identification.

Using the JavaScript agent requires at least two HTTP requests:

  • load() — the agent-download request that retrieves the latest fingerprinting logic from our CDN and collects the necessary browser attributes. This request is not billed. It must happen before sending the identification request.
  • get() — the identification request that sends the collected browser attributes to Fingerprint API and receives a visitorId in return. This request is billed and counts towards your monthly quota. It can happen only after load() (immediately or later).

By optimizing these requests and timing them right, you can make visitor identification both faster and more cost-effective.

Only use the JavaScript agent where you need it

Depending on your use case, the placement of the JavaScript agent can range from all pages of your app to specific pages and events. We recommend calling get() only when the visitorId will be used by your application. You can also choose to call get() only after the visitor gives consent to using cookies on your website.

The table below lists common use cases and recommended integration of the JavaScript agent.

Use CaseJS Agent PlacementIdentification request (get())Estimated Volume (per month)
Anonymous Visitor Identification - bulk information collection of anonymous visitorsLanding page, checkout page, etc.Page load or the start of the session (depending on your implementation)1:1 number of page loads/sessions
Account Takeover Prevention - prevent account theft using malicious login attemptsLogin page"Login" button click1:1 number of attempted logins
Securing Login & Reducing Friction - reduce login friction with conditional security checksLogin page"Login" button click1:1 number of attempted logins
Account Sharing Prevention - prevent users from sharing accountsLogin page"Login" button click1:1 number of attempted logins
Multi-account Prevention - prevent users from creating multiple accountsRegistration page"Register" button click1:1 number of attempted sign-ups
Form & Survey Abuse - protect forms from duplicate entriesForm page“Submit Form” button click1:1 number of attempted form submissions
Coupon & Promo Abuse - protect profits from duplicate promotion abuseCheckout page“Apply coupon” button click1:1 number "apply coupon" button clicks
Credit Card Fraud - block users who repeatedly use faulty credit cardsCheckout page“Checkout” button click1:1 number of checkout attempts
E-commerce Tracking - track orders made by anonymous or guest visitorsCheckout page“Checkout” button click1:1 number of checkout attempts
Paywall Circumvention - detect Incognito mode and prevent unlimited views of your paywalled contentPaywalled pagesPage load1:1 number of paywalled page loads

Pre-connect to Fingerprint URLs

API pre-connect is recommended for improved request timings. To enable it, place the preconnect directive as early as possible in your head tag:

<html>
<head>
  <link rel="preconnect" href="https://fpcdn.io">
  <link rel="preconnect" href="https://api.fpjs.io">
  ... styles, js etc
<html>
<head>
  <link rel="preconnect" href="https://fpnpmcdn.net">
  <link rel="preconnect" href="https://api.fpjs.io">
  ... styles, js etc

Pay attention to the URLs you need to pre-connect to:

  • If you are using the default (US/Global) region, pre-connect to this URL: https://api.fpjs.io
  • If you're using the EU region, pre-connect to this URL instead: https://eu.api.fpjs.io.
  • If you're using the Mumbai API, pre-connect to this URL instead: https://ap.api.fpjs.io
  • If you're using the Custom subdomain or another Proxy integration on a subdomain, use the subdomain as the pre-connect URL, for example:
<html>
<head>
  <link rel="preconnect" href="https://metrics.yourwebsite.com">

Preload the JavaScript agent

Generally, we recommend initializing the JavaScript agent (by calling FingerprintJS.load(...)) as early as possible, and requesting the visitor identifier (by calling get()) only when you need it. A good moment to load the JS agent is when your application starts.

An example of a browser application improvement:

// An instance is created when the page starts
  class MyApp {
    constructor() {
+     this.fpPromise = FingerprintJS.load({ token: '<<browserToken>>' }) 

      const button = document.querySelector('#button')
      button.addEventListener('click', this.handleClick)
    }
  
    handleClick = async () => {
-     const fp = await FingerprintJS.load({ token: '<<browserToken>>' })
+     const fp = await this.fpPromise
      const result = await fp.get()
      alert(`Your id: ${result.visitorId}`)
    }
  }

This decreases the time of getting the visitorId because the JS agent is already loaded and the browser signals are collected before the user clicks the button.

👍

Loading the JavaScript agent is free

Don't worry, the agent load request is not billed, only the identification get request counts towards your monthly plan.

Pre-request the visitor ID

You can decrease the time to get the visitor ID even more. You can call fp.get() a small time before you need the identifier. For example, when the visitor fills all the form fields or moves the cursor above the submit button. Getting the visitor ID will be in progress or complete when you need it. For example:

class MyApp {
    constructor() {
      this.fpPromise = FingerprintJS.load({ token: '<<browserToken>>' }) 

      const button = document.querySelector('#button')
+     button.addEventListener('mouseover', this.handleAboutToClick, { once: true })
      button.addEventListener('click', this.handleClick)
    }

+   handleAboutToClick = () => {
+     // in production add memoization to prevent calling `get` multiple times
+     this.fpResultPromise = this.fpPromise.then(fp => fp.get())
+   }
  
    handleClick = async () => {
-     const fp = await this.fpPromise
-     const result = await fp.get()
+     const result = await this.fpResultPromise
      alert(`Your id: ${result.visitorId}`)
    }
  }

Cache the visitor ID

Depending on your use case, your implementation might benefit from caching the visitor ID in the browser for anything between 1 to 24 hours and only calling get() when the cache expires. See Caching visitor information for more information on caching best practices.

Updated 2 months ago