Skip to content

Commit

Permalink
docs(README): improve caching explanation DOC-8 (#78)
Browse files Browse the repository at this point in the history 
* docs(README): improve caching explanation

* docs(README): minor fixes

* docs(README): small grammar fixes

* docs(README): fix badges underlines
  • Loading branch information
@JuroUhlar
JuroUhlar authored Nov 15, 2023
1 parent 3ecc488 commit 1728ece
Showing 1 changed file with 42 additions and 44 deletions.
86 changes: 42 additions & 44 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,25 +6,15 @@
<img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
</picture>
</a>
</p>
<p align="center">
<a href="https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa">
<img src="https://img.shields.io/npm/v/@fingerprintjs/fingerprintjs-pro-spa.svg" alt="Current NPM version">
</a>
<a href="https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/">
<img src="https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/badges.svg" alt="coverage">
</a>
<a href="https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa">
<img src="https://img.shields.io/npm/dm/@fingerprintjs/fingerprintjs-pro-spa.svg" alt="Monthly downloads from NPM">
</a>
<a href="https://opensource.org/licenses/MIT">
<img src="https://img.shields.io/:license-mit-blue.svg" alt="MIT license">
</a>
<a href="https://discord.gg/39EpE2neBg">
<img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server">
</a>
<a href="https://fingerprintjs.github.io/fingerprintjs-pro-spa">
<img src="https://img.shields.io/badge/-Documentation-green" alt="Documentation">
</a>
<a href="https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa" style="text-decoration: none;"><img src="https://img.shields.io/npm/v/@fingerprintjs/fingerprintjs-pro-spa.svg" alt="Current NPM version"></a>
<a href="https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/" style="text-decoration: none;"><img src="https://fingerprintjs.github.io/fingerprintjs-pro-spa/coverage/badges.svg" alt="coverage"></a>
<a href="https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro-spa"><img src="https://img.shields.io/npm/dm/@fingerprintjs/fingerprintjs-pro-spa.svg" alt="Monthly downloads from NPM"></a>
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/:license-mit-blue.svg" alt="MIT license"></a>
<a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
<a href="https://fingerprintjs.github.io/fingerprintjs-pro-spa"><img src="https://img.shields.io/badge/-Documentation-green" alt="Documentation"></a>
</p>


# Fingerprint Pro SPA
Expand Down Expand Up @@ -75,15 +65,14 @@ pnpm add @fingerprintjs/fingerprintjs-pro-spa

## Getting Started

### Fingerprint Pro public API key
### 1. Get your Fingerprint Pro Public API key

In order to identify visitors you'll need a Fingerprint Pro account (you can [sign up for free](https://dashboard.fingerprint.com/signup/)).

- Go to [Fingerprint Dashboard](https://dashboard.fingerprint.com/)
- Go to _App settings_ -> _API Keys_.
- Find your _Public_ API key
- Go to **Fingerprint Dashboard** > **App settings** > [**API Keys**](https://dashboard.fingerprint.com/api-keys).
- Find your Public API key.

### Creating the client
### 2. Create the client

Create a `FpjsClient` instance before rendering or initializing your application. You should only have one instance of the client. You need to specify your public API key and other configuration options based on your chosen region and active integration.

Expand All @@ -104,11 +93,11 @@ const fpjsClient = new FpjsClient({
}
});
```
You can learn more about different load options here in the [JS Agent documentation](https://dev.fingerprint.com/docs/js-agent#initializing-the-agent).
You can learn more about different load options in the [JS Agent API Reference](https://dev.fingerprint.com/docs/js-agent#initializing-the-agent).

### 1 - Init the JS agent
### 3. Initialize the JS Agent

Before you start making identification requests to the Fingerprint Pro API, you need to initialize the JS Agent to allow it to gather browser signals. Make sure the initialization has been completed before calling the `getVisitorData` method to avoid errors.
Before you start making identification requests to the Fingerprint Pro API, you need to initialize the JS Agent. This downloads the latest client-side logic from Fingerprint CDN. Call `init()` before the `getVisitorData()` method to avoid errors.

```js
// with async/await
Expand All @@ -121,13 +110,14 @@ const visitorData = fpjsClient.init().then(() => {
})
```

### 2 - Calling an API
The `getVisitorData` method returns visitor identification data based on the request [options](https://dev.fingerprint.com/docs/js-agent#visitor-identification).
Set `ignoreCache` to `true` to make a request to the API even if the data is present in the cache.
### 4. Identify visitors

The `getVisitorData` method returns visitor identification data based on the request [options](https://dev.fingerprint.com/docs/js-agent#get-options).
Set `ignoreCache` to `true` to call the API even if the data is present in the cache.

```js
// with async/await
const visitorData = await fpjsClient.getVisitorData({ extendedResult: true })
const visitorData = await fpjsClient.getVisitorData({ extendedResult: true, ignoreCache: false })

// with promises
const visitorData = fpjsClient.getVisitorData({ extendedResult: true }).then((visitorData) => {
Expand All @@ -136,32 +126,39 @@ const visitorData = fpjsClient.getVisitorData({ extendedResult: true }).then((vi
})
```

See the [JS Agent API reference](https://dev.fingerprint.com/docs/js-agent) for more details.

### Caching

The SDK can cache the visitor data in session storage (default), in local storage, or in memory.
You can specify the `cacheLocation` option when creating the Fpjs client.
Fingerprint Pro usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results. The SDK provides three ways to cache visitor data out of the box:

* Session storage (default) - `sessionStorage`
* Local storage - `localStorage`
* Memory - `memory`
* No cache - `nocache`

You can specify the `cacheLocation` option when creating the `FpjsClient`:

```js
const fpjsClient = new FpjsClient({
loadOptions: {
apiKey: "your-fpjs-public-api-key"
},
cacheLocation: 'localstorage'
});
```

Or if you are using TypeScript:
```ts
const fpjsClient = new FpjsClient({
loadOptions: {
apiKey: "your-fpjs-public-api-key"
},
cacheLocation: CacheLocation.LocalStorage
// You can also use the provided TypeScript enum
// cacheLocation: CacheLocation.LocalStorage
});
```

Cache keys are based on the combination of _GetOptions_. For example, API responses for calls with `extendedResult: true` and `extendedResult: false` are stored independently.

* You can ignore the cached result for a specific API call by passing `{ ignoreCache: true }` to the `getVisitorData()` method.
* You can also use your custom cache implementation as described below.

> [!NOTE]
> If you use data from [`extendedResult`](https://dev.fingerprint.com/docs/js-agent#extendedresult), pay additional attention to your caching strategy.
> Some fields, for example, `ip` or `lastSeenAt`, might change over time for the same visitor. Use `getVisitorData({ ignoreCache: true })` to fetch the latest identification results.
#### Creating a custom cache

The SDK can use a custom cache store implemented inside your application. This is useful when a different data store is more convenient in your environment, such as a hybrid mobile app.
Expand All @@ -175,7 +172,8 @@ You can provide an object to the `cache` property of the SDK configuration that
| `remove(key)` | Promise<void> or void | Removes a single item from the cache at the specified key, or no-op if the item was not found |
| `allKeys()` | Promise<string[]> or string [] | Returns the list of all keys. By default, the keys we use are prefixed with `@fpjs@client@` but you can pass your own custom prefix as an option when you create the FpjsClient |

**Note:** The `cache` property takes priority over `cacheLocation` if both are set. A warning is displayed in the console if that happens.
> [!NOTE]
> The `cache` property takes priority over `cacheLocation` if both are set. A warning is displayed in the console if that happens.
We export the internal `InMemoryCache`, `LocalStorageCache`, `SessionStorageCache`, and `CacheStub` implementations, so you can wrap your custom cache around these implementations if you wish.

Expand All @@ -184,7 +182,7 @@ Use the `cacheTimeInSeconds` client constructor option to set a custom cache tim

## Support and feedback

To report problems, ask questions or provide feedback, please use [Issues](https://github.com/fingerprintjs/fingerprintjs-pro-spa/issues). If you need private support, you can email us at [[email protected]](mailto:[email protected]).
To report problems, ask questions, or provide feedback, please use [Issues](https://github.com/fingerprintjs/fingerprintjs-pro-spa/issues). If you need private support, you can email us at [[email protected]](mailto:[email protected]).

## Documentation

Expand Down

0 comments on commit 1728ece

Please sign in to comment.