start function

API reference for the JavaScript agent’s start() function

This page contains the API Reference for the JavaScript agent’s start() function or its equivalent in your frontend library. The function is exported from the @fingerprint/agent NPM package.

Call the start() function to initialize the JavaScript agent for your Fingerprint workspace.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

• Install the JavaScript agent
• Identify visitors

start() options

To configure the agent, pass parameters into the start() function.

apiKey

Required: yes for NPM installation Type: string

Your public API key to authenticate the agent. You can get one at dashboard.fingerprint.com. If you log into this documentation portal through the dashboard, you will be able to see your personal API key in the example below.

Example usage:

JavaScript

Fingerprint.start({ apiKey: "<<browserToken>>" })

The parameter is required for the NPM installation method and optional for the CDN (where the key is a part of the URL).

region

Required: no Default: "us" Type: string Available values: "us", "eu" and "ap"

Use this parameter to specify the region you picked for your workspace during registration (defaults to us).

The Fingerprint Platform CDN can usually determine the region automatically using your API Key. Nevertheless, we recommend you specify it explicitly. Our proxy integrations rely on the region parameter, as they do not have access to the same internal API that our CDN does. Even if you use our CDN, specifying the region explicitly will keep your JS agent working correctly if our internal API is temporarily disrupted.

Example:

JavaScript

const fp = Fingerprint.start({ region: 'eu' })

endpoints

Required: no Default: (depends on the region) Type: string | string[]

This parameter should only be used with the Custom subdomain or a cloud proxy integration. Specify your custom endpoint URL here.

Multiple endpoints can be set using an array. The JS agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint, and so on. Use Fingerprint.withoutDefault() helper if you want to disable our standard fallback endpoints.

Endpoints

import * as Fingerprint from '@fingerprint/agent'

const fp = Fingerprint.start({
  apiKey: 'your-public-api-key',
  endpoints: 'https://fp.example.com'
})

JS agent will throw an error if an empty array is given.

storageKeyPrefix

Required: no Default: '_vid_' Type: string

Name of the key to store visitor data in browsers. The data is stored in cookies and local storage. You shouldn’t change this parameter once your code runs in production. The change will cause the data in visitor browsers to be purged which will decrease the identification accuracy.

urlHashing

Only for NPM installation Required: no Default: undefined (no hashing) Type: UrlHashing Since: v3.11.0

urlHashing flags ensure no PII or secret data get unintentionally leaked through path, query or fragment values in an URL by replacing raw values with a securely encoded hash.

urlHashing configuration has no effect on performance or accuracy of Identification and Smart Signals products.

The UrlHashing type has the following configuration structure

UrlHashing

type UrlHashing = {
  path?: boolean
  query?: boolean
  fragment?: boolean
}

• path replaces the path portion of the URL with a securely encoded hash if set to true
• query replaces the query portion of the URL with a securely encoded hash if set to true
• fragment replaces the fragment portion of the URL with a securely encoded hash if set to true

The portion of the URL that contains either path, query or fragment is replaced with a single value that represents a securely encoded hash of the original URL parts.

Example:

The following example illustrates the behavior of our JS agent without and with the urlHashing flags configured. Original URL represents the URL we would normally send to our backend (in an obfuscated form) Result shows how our JS agent hashes the URL if the path, query and fragment parameters of urlHashing were set to true respectively. The order of the query parameters has no effect on the output hash.

Original URL

https://example.com/test?param1=somePII&param2=clientSecret&param3=tokenValue#id342324

path enabled	query enabled	fragment enabled	Result
NO	YES	NO	https://example.com/test?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#id342324
YES	NO	NO	https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?param1=somePII&param2=clientSecret&param3=tokenValue#id342324
NO	NO	YES	https://example.com/test?param1=somePII&param2=clientSecret&param3=tokenValue#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo
YES	YES	YES	https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo

If either query, param or fragment part are empty, they are returned as-is without hashing. As an example URL https://example.com/?# stays as is.

cache

Only for NPM installation Required: no Default: undefined (do not use cache) Type: CacheConfig Since: v4.0.0

Added in version 4, the JavaScript agent now contains predefined caching options. By default, the agent does not cache any information and every call to get() results in a full billable event (sending signals to our backend and receiving a result). This is because caching can be detrimental to the accuracy and efficacy of our products (both Identification, and more prominently Smart Signals).

CacheConfig

The full CacheConfig type definition is

CacheConfig

type CacheConfig =
  | false
  | {
      storage: 'sessionStorage' | 'localStorage' | 'agent' // this is a "memory" storage
      duration: 'optimize-cost' | 'aggressive'  | number
      cachePrefix?: string
    }

where

storage determines where the JavaScript agent stores the cached information, by default it stores the information in memory (agent option).

Each storage option has the following semantics

• sessionStorage means the cached information is stored in the Session Storage and clears when the browser/tab gets closed. Session storage outlives page refreshes as long as the same tab and origin remain open.
• localStorage means that the cached information is stored in the Local Storage and outlives browser restarts (and never expires by default).
• agent means that the cached information is stored in memory and clears with page (and agent) reloads.

duration represents the amount of time needed to clear the cache, it supports two predefined values and an arbitrary number option (with an upper limit).

• optimize-cost stores information in cache for 1 hour
• aggressive stores information in cache for 12 hours (we don’t recommend using aggressive in fraud protection use cases)
• when supplied with a number, the agent stores the cache information for the exact number of seconds. Maximum value is 43200 and the agent will throw an error when a higher value was used.

cachePrefix is a prefix of the string key used to store the cached information (applies to sessionStorage and localStorage storage options).

start() response

The start() function synchronously returns the JavaScript agent instance. The instance has a get() method you can use to identify visitors. Always call the start() method as soon as possible on the page as it influences how long does the get() method take to finish and return results.

JavaScript

import * as Fingerprint from '@fingerprint/agent';

async function identifyVisitor() {
  const agent = Fingerprint.start({ apiKey: 'PUBLIC_API_KEY' })
  const result = await agent.get()
  console.log(result.visitor_id)
}

See Configuring the JavaScript agent for more details.