Fingerprint Svelte SDK

Fingerprint is a device intelligence platform offering industry-leading accuracy.

Fingerprint Svelte SDK is an easy way to integrate Fingerprint into your Svelte or Svelte-kit application. See example apps in the examples folder.

Requirements

• Svelte 4.0.0 or higher
• For TypeScript users: TypeScript 4.8 or higher
• For SvelteKit users: SvelteKit 1.0.0 or higher

Svelte 5 compatibility

The SDK uses the Svelte 4 API (stores, $store syntax) and works in Svelte 5 unchanged thanks to the compiler's built-in legacy mode.

This package works with the commercial Fingerprint platform. It is not compatible with the open-source FingerprintJS library. Learn more about the differences between Fingerprint and FingerprintJS.

Installation

Yarn:

yarn add @fingerprint/svelte

npm:

npm install @fingerprint/svelte

pnpm:

pnpm add @fingerprint/svelte

Getting started

In order to identify visitors, you'll need a Fingerprint Pro account (you can sign up for free). To get your API key and get started, see the Quick start guide in our documentation.

1. Wrap your application (or component) in FingerprintProvider. You can specify multiple configuration options. Set a region if you have chosen a non-global region during registration. Set endpoints if you are using one of our proxy integrations to increase accuracy and effectiveness of visitor identification.

// App.svelte
<script>
  import { FingerprintProvider } from '@fingerprint/svelte'
  import VisitorData from './VisitorData.svelte'

  const options = {
    apiKey: '<YOUR_API_KEY>',
    endpoints: ['https://metrics.yourwebsite.com'],
    region: 'eu',
  }
</script>

<FingerprintProvider {options}>
  <VisitorData />
</FingerprintProvider>

2. Use the useVisitorData function in your Svelte components to identify visitors and get the results.

// VisitorData.svelte
<script>
  import { useVisitorData } from '@fingerprint/svelte'

  const { getData, data, isLoading, isFetched, error } = useVisitorData({ immediate: true })

  async function handleClick() {
    try {
      await getData()
    } catch {
      // Error is available in the $error store
    }
  }
</script>

<div>
  <button on:click={handleClick}>Get data</button>
  {#if $isLoading}
    <div>Loading...</div>
  {/if}
  {#if $error}
    <div>Error: {$error.message}</div>
  {/if}
  {#if $data}
    <pre>{JSON.stringify($data, null, 2)}</pre>
  {/if}
</div>

See the full code in the provided example applications.

Linking and tagging information

The visitor_id provided by Fingerprint Identification is especially useful when combined with information you already know about your users, for example, account IDs, order IDs, etc. To learn more about various applications of the linkedId and tag, see Linking and tagging information.

Associate the visitor ID with your data using the linkedId or tag parameter of the options object passed into the useVisitorData() hook:

<script>
  import { useVisitorData } from '@fingerprint/svelte'

  const { getData, data, isLoading, error } = useVisitorData({
    linkedId: 'user_1234',
    tag: {
      userAction: 'login',
      analyticsId: 'UA-5555-1111-1',
    },
  })
</script>

Caching strategy

Fingerprint Pro usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results.

Starting with JS Agent v4, there is no caching by default. To enable caching, pass a cache option to FingerprintProvider:

<script>
  import { FingerprintProvider } from '@fingerprint/svelte'

  const options = {
    apiKey: '<YOUR_API_KEY>',
    cache: {
      storage: 'sessionStorage',
      duration: 3600, // 1 hour in seconds (max 43200)
    },
  }
</script>

<FingerprintProvider {options}>
  <VisitorData />
</FingerprintProvider>

See the JS Agent caching documentation for more details.

Migration from v2.x

Version 3.0 upgrades the underlying Fingerprint agent from v3 to v4 and introduces several breaking changes. See the migration guide for detailed instructions and the JavaScript agent v3 to v4 migration guide for underlying agent changes.

Documentation

See the generated SDK API reference here.

This library uses Fingerprint Pro JavaScript agent under the hood. See our documentation for the full JavaScript Agent API reference.

Error handling

getData() rethrows errors from the JS Agent after storing them in the error store. Non-Error values are normalized into Error instances. See JS Agent error handling for more details.

Support and feedback

To report problems, ask questions or provide feedback, please use Issues. If you need private support, you can email us at oss-support@fingerprint.com.

License

This project is licensed under the MIT license.