@fingerprint/angular

Fingerprint logo

CI badge Coverage Status Current NPM version Monthly downloads from NPM MIT license Discord server Documentation

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

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 {}
  1. 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 tag, see Linking and tagging information.

Associate your data with an identification event using the linkedId or tag 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',
      tag: {
        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',
      tag: {
        userAction: 'login',
        analyticsId: 'UA-5555-1111-1',
      },
    })

    // ...
  }
}

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.
tag Fingerprint.TagValue No A user-provided value or object that will be returned back to you in a webhook message.
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 git@github.com: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 oss-support@fingerprint.com. 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.

Settings

Member Visibility

Theme

On This Page

Generated using TypeDoc