Fingerprint Angular

Fingerprint Angular SDK is an easy way to integrate Fingerprint into your Angular application. See the src folder for a full usage example.

This SDK supports v4 of the Fingerprint JavaScript agent. See the v3 to v4 migration guide for more information.

Table of contents

• Requirements
• Installation
• Getting started
• Caching strategy
• Documentation
• Version support
• Support and feedback
• License

Requirements

The following dependencies are required:

• TypeScript >=4.6
• Node 16+
• Angular 15+

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

Installation

Using npm:

npm install @fingerprint/angular

Using pnpm:

pnpm add @fingerprint/angular

Using yarn:

yarn add @fingerprint/angular

Getting started

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

1. Add provideFingerprint to your providers array (for standalone applications) or FingerprintModule.forRoot() to the imports section (for NgModule applications), and pass it the startOptions configuration object. 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. Read more about other forRoot() / provideFingerprint() parameters below.

Standalone application example:

import { ApplicationConfig } from '@angular/core';
import { provideFingerprint } from '@fingerprint/angular';

export const appConfig: ApplicationConfig = {
  providers: [
    provideFingerprint({
      startOptions: {
        apiKey: '<PUBLIC_API_KEY>',
        endpoints: 'https://metrics.yourwebsite.com',
        // region: 'eu',
      },
    }),
  ],
}

Legacy NgModule application example:

import { NgModule } from '@angular/core'
import { FingerprintModule, Fingerprint } from '@fingerprint/angular'

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,

    // Add this block
    FingerprintModule.forRoot({
      startOptions: {
        apiKey: '<PUBLIC_API_KEY>',
        endpoints: 'https://metrics.yourwebsite.com',
        // region: "eu"
      },
    }),
  ],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

2. Inject FingerprintService in your component using inject(). Now you can identify visitors using the getVisitorData() method.

Standalone application example (Angular 16+):

import { Component, inject, signal } from '@angular/core'
import { FingerprintService } from '@fingerprint/angular'

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrl: './home.component.css',
})
export class HomeComponent {
  private fingerprintService = inject(FingerprintService)

  eventId = signal('Press "Identify" button to get eventId')

  async onIdentifyButtonClick(): Promise<void> {
    const data = await this.fingerprintService.getVisitorData()
    this.eventId.set(data.event_id)
  }
}

Legacy NgModule application example:

import { Component } from '@angular/core'
import { FingerprintService } from '@fingerprint/angular'

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.css'],
})
export class HomeComponent {
  constructor(private fingerprintService: FingerprintService) {}

  eventId = 'Press "Identify" button to get eventId'

  async onIdentifyButtonClick(): Promise<void> {
    const data = await this.fingerprintService.getVisitorData()
    this.eventId = data.event_id
  }
}

Server-side rendering (SSR) with Angular SSR

The library can be used with Angular SSR. Keep in mind that visitor identification is only possible in the browser, so your visitor identification code should only run client-side. See the example implementation for more details.

Linking and tagging information

The event_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 tags, see Linking and tagging information.

Associate your data with an identification event using the linkedId or tags parameter of the options object passed into the getVisitorData() method:

Standalone application example (Angular 16+):

// ...

import { Component, inject } from '@angular/core'
import { FingerprintService } from '@fingerprint/angular'

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrl: './home.component.css',
})
export class HomeComponent {
  private fingerprintService = inject(FingerprintService)

  async onIdentifyButtonClick(): Promise<void> {
    const data = await this.fingerprintService.getVisitorData({
      linkedId: 'user_1234',
      tags: {
        userAction: 'login',
        analyticsId: 'UA-5555-1111-1',
      },
    })

    // ...
  }
}

Legacy NgModule application example:

// ...

import { Component } from '@angular/core'
import { FingerprintService } from '@fingerprint/angular'

@Component({
  selector: 'app-home',
  templateUrl: './home.component.html',
  styleUrls: ['./home.component.css'],
})
export class HomeComponent {
  constructor(private fingerprintService: FingerprintService) {}

  async onIdentifyButtonClick(): Promise<void> {
    const data = await this.fingerprintService.getVisitorData({
      linkedId: 'user_1234',
      tags: {
        userAction: 'login',
        analyticsId: 'UA-5555-1111-1',
      },
    })

    // ...
  }
}

[!NOTE] The tag option is deprecated in favor of tags. tag still works, but if both are provided, tags takes precedence.

Caching strategy

Fingerprint usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results. By default, the SDK does not use caching.

• Specify cache on the FingerprintModule.forRoot props or provideFingerprint options to enable and configure caching.
• For more details, see Caching results.

[!NOTE] 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.

Documentation

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

FingerprintModule and provideFingerprint

The library provides two ways to initialize the Fingerprint JS agent and provide FingerprintService to your application: FingerprintModule (for NgModule-based applications) and provideFingerprint (for standalone applications).

FingerprintModule.forRoot props / provideFingerprint options

{ startOptions: Fingerprint.StartOptions }

Options for the Fingerprint JS agent. Options follow the agent's initialization properties.

| Property | Type | Required | Description | |--------------------------|---------------------------|----------|-----------------------------------------------------------------------------------| | apiKey | string | Yes | Your public API key. | | region | string | No | The region where your data is stored. Can be us, eu or ap. Default is us. | | endpoints | Fingerprint.Endpoint | No | Custom API endpoints. | | storageKeyPrefix | string | No | Custom prefix for storage keys (e.g. cookies). Default is _vid_. | | integrationInfo | string[] | No | Information about the integration. | | remoteControlDetection | boolean | No | Whether to enable remote control detection. | | urlHashing | Fingerprint.UrlHashing | No | Configuration for URL hashing. | | cache | Fingerprint.CacheConfig | No | Configuration for caching. |

Fingerprint.Endpoint

An endpoint for a specific HTTPS request. Can be a single URL string, an array of strings, or wrapped with withoutDefault(...) to disable fallback.

Fingerprint.UrlHashing

Hashes URL parts before sending them to the Fingerprint server.

| Property | Type | Required | Description | |------------|-----------|----------|--------------------------------------------------------------| | path | boolean | No | Set to true to hash the path part of the URL. | | query | boolean | No | Set to true to hash the query part of the URL. | | fragment | boolean | No | Set to true to hash the fragment part of the URL. |

Fingerprint.CacheConfig

Configuration for caching agent results.

| Property | Type | Required | Description | |---------------|-------------------------------------------|----------|---------------------------------------------------------------------------------------------------------------| | storage | sessionStorage, localStorage, agent | Yes | Where to store the cached results. | | duration | optimize-cost, aggressive, number | Yes | Caching strategy or duration in seconds. optimize-cost (default), aggressive or custom number of seconds. | | cachePrefix | string | No | Custom prefix for cache keys. |

FingerprintService methods

getVisitorData(options?: Fingerprint.GetOptions): Promise<Fingerprint.GetResult>

This method performs identification requests with the FingerprintJS Pro API.

• options: Fingerprint.GetOptions parameter follows the parameters of the FingerprintJS Pro's get function.

| Property | Type | Required | Description | |------------|------------------------|----------|-----------------------------------------------------------------------------------------| | timeout | number | No | Total time (in ms) allowed for the identification event. Default is 10000. | | tags | Fingerprint.TagValue | No | A user-provided value or object that will be returned back to you in a webhook message. | | tag | Fingerprint.TagValue | No | Deprecated. Use tags instead. | | linkedId | string | No | A way of linking current identification event with a custom identifier. |

Legacy Demo application

This repository contains an example Angular application. To run the demo locally:

1. Clone the repository with git clone [email protected]:fingerprintjs/angular.git.
2. Inside the root folder, run pnpm install to install the dependencies.
3. Create a dev environment file with cp src/environments/environment.ts src/environments/environment.dev.ts, and inside, replace Fingerprint public key with your actual public key.
4. Run pnpm generate:version to create an SDK version file.
5. Run pnpm start to start the demo application. (The app will now use the internal library source directly).

The application will start on http://localhost:4200.

Angular 21 Demo Application

This repository also contains an example Angular application that uses Angular 21. To run the demo locally, apply the same steps as above with key differences:

1. Navigate into projects/demo-angular21 folder. Run cd projects/demo-angular21 after you clone the repository.
2. Run pnpm install to install the dependencies.
3. Create a dev environment file with cp projects/demo-angular21/src/environments/environment.ts projects/demo-angular21/src/environments/environment.dev.ts, and inside, replace Fingerprint public key with your actual public key.
4. Simply run pnpm ng serve to start the demo application.

Version support

| SDK major version | JS Agent version | Status | End of support | |---|---|---|---| | v3.x (current) | v4 | Supported | - | | v1.x-v2.x | v3 | Deprecated (security fixes only). See the migration guide. | To be decided |

Support and feedback

To ask questions or provide feedback, use Issues. If you need private support, please email us at [email protected]. If you'd like to have a similar Angular wrapper for the source-available FingerprintJS, consider creating an issue in the main FingerprintJS repository.

API Reference

See the full generated API reference.

License

This project is licensed under the MIT license. See the LICENSE file for more info.