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;
       }
    };
};

Next Steps

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