@fingerprintjs/fingerprintjs-pro-angular
v2.0.0
Published
FingerprintJS Pro Angular SDK
Downloads
5,664
Readme
Fingerprint Pro Angular
Fingerprint Pro Angular SDK is an easy way to integrate Fingerprint Pro into your Angular application. See the src
folder for a full usage example.
This package works with Fingerprint Pro, it is not compatible with the open-source FingerprintJS. See our documentation to learn more about the difference between Fingerprint Pro and the open-source FingerprintJS.
Table of contents
Requirements
The following dependencies are required:
- TypeScript >=4.6
- Node 16+
- Angular 15+
Installation
Using npm:
npm install @fingerprintjs/fingerprintjs-pro-angular
Using yarn:
yarn add @fingerprintjs/fingerprintjs-pro-angular
Getting started
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.
- Add
FingerprintjsProAngularModule.forRoot()
to the imports sections in your root application module and pass it theloadOptions
configuration object. You can specify multiple configuration options. Set a region if you have chosen a non-global region during registration. Setendpoint
andscriptUrlPattern
if you are using one of our proxy integrations to increase accuracy and effectiveness of visitor identification. Read more about other forRoot() parameters below.
import { NgModule } from '@angular/core';
import {
FingerprintjsProAngularModule,
// defaultEndpoint,
// defaultScriptUrlPattern,
} from '@fingerprintjs/fingerprintjs-pro-angular';
// ...
@NgModule({
declarations: [AppComponent],
imports: [
BrowserModule,
FingerprintjsProAngularModule.forRoot({
loadOptions: {
apiKey: 'your-fpjs-public-api-key',
// region: 'eu',
// endpoint: ['metrics.yourwebsite.com', defaultEndpoint],
// scriptUrlPattern: ['metrics.yourwebsite.com/agent-path', defaultScriptUrlPattern],
}
})
],
providers: [],
bootstrap: [AppComponent]
})
export class AppModule { }
- Inject
FingerprintjsProAngularService
in your component's constructor. Now you can identify visitors using thegetVisitorData()
method.
import { Component } from '@angular/core';
import { FingerprintjsProAngularService } from '@fingerprintjs/fingerprintjs-pro-angular';
@Component({
selector: 'app-home',
templateUrl: './home.component.html',
styleUrls: ['./home.component.css']
})
export class HomeComponent {
constructor(private fingerprintjsProAngularService: FingerprintjsProAngularService) {}
//^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
visitorId = 'Press "Identify" button to get visitorId';
extendedResult: null | ExtendedGetResult | GetResult = null;
async onIdentifyButtonClick() : Promise<void> {
const data = await this.fingerprintjsProAngularService.getVisitorData();
// ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
this.visitorId = data.visitorId;
this.extendedResult = data;
}
}
Server-side rendering (SSR) with Angular Universal
The library can be used with Angular Universal. 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 visitorId
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 a visitor ID using the linkedId
or tag
parameter of the options object passed into the useVisitorData()
hook or the getData
function:
// ...
import { Component } from '@angular/core';
import { FingerprintjsProAngularService } from '@fingerprintjs/fingerprintjs-pro-angular';
@Component({
selector: 'app-home',
templateUrl: './home.component.html',
styleUrls: ['./home.component.css']
})
export class HomeComponent {
constructor(private fingerprintjsProAngularService: FingerprintjsProAngularService) {}
async onIdentifyButtonClick() : Promise<void> {
const data = await this.fingerprintjsProAngularService.getVisitorData({
linkedId: "user_1234",
tag: {
userAction: "login",
analyticsId: "UA-5555-1111-1"
}
});
// ...
}
}
Caching strategy
Fingerprint Pro usage is billed per API call. To avoid unnecessary API calls, it is a good practice to cache identification results. By default, the SDK uses sessionStorage
to cache results.
- Specify
cacheLocation
on theFingerprintjsProAngularModule.forRoot
props to instead store results inmemory
orlocalStorage
. Usenone
to disable caching completely. - Specify
cache
on theFingerprintjsProAngularModule.forRoot
props to use your custom cache implementation instead. For more details, see Creating a custom cache in the Fingerprint Pro SPA repository (a lower-level Fingerprint library used by this SDK). - Pass
{ignoreCache: true}
to thegetVisitorData()
function to ignore cached results for that specific API call.
[!NOTE] If you use data from
extendedResult
, pay additional attention to your caching strategy. Some fields, for example,ip
orlastSeenAt
, might change over time for the same visitor. UsegetVisitorData({ ignoreCache: true })
to fetch the latest identification results.
Documentation
This library uses Fingerprint Pro JavaScript agent under the hood. See our documentation for the full JavaScript Agent API reference.j
FingerprintjsProAngularModule
The module just initializes the Fingerprint Pro JS agent with load options, configures caching strategy, and provides FingerprintjsProAngularService
to DI.
FingerprintjsProAngularModule.forRoot
props
loadOptions: FingerprintJS.LoadOptions
Options for the FingerprintJS JS Pro agent load()
method. Options follow the agent's initialization properties.
cacheLocation?: CacheLocation
Defines which built-in cache mechanism the client should use. Caching options follow properties defined in the fingerprintjs-pro-spa repository.
cache?: ICache
Custom cache implementation. Takes precedence over the cacheLocation
property. Caching options follow properties defined in the fingerprintjs-pro-spa repository.
cacheTimeInSeconds?: number
Duration in seconds for which data is stored in the cache. Cannot exceed 86_400 (24h) because caching data for longer than 24 hours can negatively affect identification accuracy. Caching options follow properties defined in the fingerprintjs-pro-spa repository.
cachePrefix?: string
Custom prefix for localStorage and sessionStorage cache keys. Will be ignored if the cache
is provided. Caching options follow properties defined in the fingerprintjs-pro-spa repository.
FingerprintjsProAngularService
methods
getVisitorData(ignoreCache?: boolean, options?: GetOptions<TExtended>)
This method performs identification requests with the FingerprintJS Pro API. The returned object contains information about loading status, errors, and the visitor.
getOptions: GetOptions<TExtended>
parameter follows the parameters of the FingerprintJS Pro'sget
function.ignoreCache: boolean
- set totrue
to always make a request to the API, even if the data is present in the cache.
clearCache
Clears the cache for the current caching strategy.
Demo application
This repository contains an example Angular application. To run the demo locally:
- Clone the repository with
git clone [email protected]:fingerprintjs/fingerprintjs-pro-angular.git
. - Inside the root folder, run
yarn install
to install the dependencies. - Create a dev environment file with
cp src/environments/environment.ts src/environments/environment.dev.ts
, and inside, replaceFingerprintJS Pro public key
with your actual public key. - Run
yarn generate:version
to create an SDK version file. - Run
yarn build
to build the SDK package. - Run
yarn start
to start the demo application.
The application will start on http://localhost:4200.
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 open-source 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.