> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://www.npmjs.com/package/@fingerprint/agent) NPM package.

The `start()` function initializes the JavaScript agent for your Fingerprint workspace, which you can then use to identify visitors. When you call `start()`, the agent begins collecting the signals required for Identification and Smart Signals. Call `start()` as soon as possible, ideally right after the page loads.

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

* [Install the JavaScript agent](/docs/install-the-javascript-agent)
* [Identify visitors](/docs/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](https://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:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  Fingerprint.start({ apiKey: "<<browserToken>>" })
  ```
</CodeGroup>

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](/docs/regions) you picked for your workspace during registration (defaults to `us`).

The Fingerprint Platform CDN can usually determine the region automatically using your API Key. Even so, specifying it explicitly is recommended: it keeps your JavaScript agent working correctly even if the Fingerprint internal API is temporarily disrupted. With the [Custom subdomain setup](/docs/custom-subdomain-setup), this `region` option is also how the agent picks the correct regional API.

<Note>
  **Using a proxy integration?** [Proxy integrations](/docs/protecting-the-javascript-agent-from-adblockers) route to the correct regional API using a `region` **query parameter in the `endpoints` URL**, not this top-level `region` option. Include the region in the `endpoints` URL, for example `endpoints: 'https://yourwebsite.com/INTEGRATION_PATH/?region=eu'`. See your integration's guide for details.
</Note>

Example:

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  const fp = Fingerprint.start({ region: 'eu' })
  ```
</CodeGroup>

### `endpoints`

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

This parameter should only be used with the [Custom subdomain](/docs/custom-subdomain-setup#4-configuring-the-javascript-agent) or a cloud [proxy integration](/docs/protecting-the-javascript-agent-from-adblockers). Specify your custom endpoint URL here.

Multiple endpoints can be set using an array. The JavaScript 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.

<CodeGroup>
  ```javascript Endpoints theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: 'https://fp.example.com'
  })
  ```

  ```javascript No default endpoints theme={"theme":"github-dark-dimmed"}
  import * as Fingerprint from '@fingerprint/agent'

  const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    endpoints: Fingerprint.withoutDefault('https://fp.example.com')
  })
  ```
</CodeGroup>

JavaScript 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.

<Info>
  `urlHashing` configuration has no effect on performance or accuracy of Identification and Smart Signals products.
</Info>

The `UrlHashing` type has the following configuration structure

<CodeGroup>
  ```typescript UrlHashing theme={"theme":"github-dark-dimmed"}
  type UrlHashing = {
    path?: boolean
    query?: boolean
    fragment?: boolean
  }
  ```
</CodeGroup>

* `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 JavaScript 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 JavaScript 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` |

<Info>
  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.
</Info>

### `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

<CodeGroup>
  ```typescript CacheConfig theme={"theme":"github-dark-dimmed"}
  type CacheConfig =
    | false
    | {
        storage: 'sessionStorage' | 'localStorage' | 'agent' // this is a "memory" storage
        duration: 'optimize-cost' | 'aggressive'  | number
        cachePrefix?: string
      }
  ```
</CodeGroup>

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](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage) 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](https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage) 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()`](/reference/js-agent-get-function) method you can use to identify visitors.

<CodeGroup>
  ```javascript JavaScript theme={"theme":"github-dark-dimmed"}
  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)
  }
  ```
</CodeGroup>

See [Configuring the JavaScript agent](/docs/install-the-javascript-agent#configuring-the-agent) for more details.