Quick Start

Installation

Prerequisites

Node.js version 14 or higher is recommended.

How to Install

First, install the npm package using the command below

npm install @innerworks-me/iw-auth-sdk

Initialise

Import SDK

Import the SDK on the page you'd like to send metrics from

import { InnerworksMetrics, InnerworksResponse } from "@innerworks-me/iw-auth-sdk";

Setting up the SDK

To use the innerworks SDK, the InnerworksMetrics class must be initialised with your project ID.

const [innerworksMetrics, setInnerworksMetrics] = useState<InnerworksMetrics|null>();

useEffect(() => {
  setInnerworksMetrics(
    new InnerworksMetrics({
      appId: 'your-project-id'
    })
  );
}, []);

Send Data

Warning

Avoid using any personal data for the user-id, including but not limited to email addresses, names, or other identifiers that can be used to identify an individual. Innerworks does not agree to process personal data entered here.

Sending Data

Once the InnerworksMetrics object is initialised, the data must be sent at the point at which you want to analyse a user session.

if (innerworksMetrics) {
    await innerworksMetrics.send('user-id');
}

The user-id is used to associate data with a user on your platform. This is typically a UUID that you have access to. Examples include Web3 Wallet Addresses and Usernames.

Fingerprinting

For fingerprinting, you will receive a request id, which can then be used to retrieve the fingerprint via an additional request via your backend. See our API Access guide for more information

if (innerworksMetrics) {
    const response: InnerworksResponse = await innerworksMetrics.send('my-user-id');
    if (response.result === 'success') {
        // Fingerprinting Result - the request id is used to make a backend request
        const request_id = response.requestId;
    };
};

Note

For security reasons the fingerprint is not provided as a JWT in the frontend, this needs to be retrieved through a backend connection

VPN Detection

A VPN result is delivered via JWT. To see how to validate this JWT through a JWKS certificate, see our JWT Verification guide.

import { jwtDecode } from 'jwt-decode';
  
if(innerworksMetrics) {
    const response: InnerworksResponse = await innerworksMetrics.send('my-user-id');
    if(response.result === 'success') {
        // VPN Result
        const token = response.detectionResultJwt;
        if (token) {
            const decodedResult = jwtDecode(token);
            const vpnResult = decodedResult.detectionResult.geolocation; 
            const vpnIsEnabled: boolean = vpnResult.vpnIsEnabled;
            const trueGeoLocationName: string = vpnResult.trueGeoLocationName; // e.g. "United Kingdom"
            const trueGeoLocationCode: string = vpnResult.trueGeoLocationCode; // e.g. "GB"
            const vpnLocationCode: string = vpnResult.vpnLocationCode;
            const stateUS: string = vpnResult.stateUS;
       }
    };
};

Content Security Policy

The Innerworks SDK uses a dynamic loading mechanism to keep the core metrics collection system always up to date to ensure the most accurate results and browser compatibility.

Note

Content Security Policy rules are permissive by default. If your website does not enforce any CSP rules, no additional configuration is required.

Strict CSP Configuration

If your website enforces strict Content Security Policy headers, you must whitelist our SDK CDN domain as a trusted JavaScript source. Add the following domain to your CSP `script-src` or `default-src` directive:

sdk-cdn.prod.innerworks.me

Example CSP Headers

Here are examples of how to configure your CSP header to allow the Innerworks SDK dynamic loading:

Using the `script-src` directive:

Content-Security-Policy: script-src 'self' https://sdk-cdn.prod.innerworks.me;

Using the `default-src` directive with a specific `script-src` override:

Content-Security-Policy: default-src 'self'; script-src 'self' https://sdk-cdn.prod.innerworks.me;

Warning

If you are enforcing strict CSP rules and do not whitelist this domain, the SDK will fail to load its core components and will not function correctly.

Next Steps

To access fingerprinting information, see our API Access guide
To validate the JWT returned from the SDK, see our JWT Verification guide