@incognia/web-sdk v1.2.0

Incognia Web SDK

The Incognia SDK for the web.

Documentation can be found at https://developer.incognia.com/docs

Installation

npm

npm install @incognia/web-sdk

pnpm

pnpm install @incognia/web-sdk

yarn

yarn add @incognia/web-sdk

CDN

Add the following script to your HTML:

<script src="https://repo.incognia.com/web/latest/incognia-web-sdk.js"></script>

Getting started

Import the package:

// ES6
import IncogniaWebSdk from '@incognia/web-sdk'

// CommonJS (Outdated)
const IncogniaWebSdk = require('@incognia/web-sdk')

// CDN Script
const IncogniaWebSdk = window.IncogniaWebSdk

Library API methods

Init

Initialize the Web SDK with your Web Application ID. This step is required, and further methods will not work if the SDK is not initialized.

IncogniaWebSdk.init('<your-web-app-id>')

Account ID

The method setAccountId receives an account ID and stores locally. It is then added to the requestToken data.

IncogniaWebSdk.setAccountId('@accountId')

The method clearAccountId removes the account ID from the local storage.

IncogniaWebSdk.clearAccountId()

Generate request token

This method generates a request token and returns it.

const requestToken = await IncogniaWebSdk.generateRequestToken()

Send custom event

This method sends a custom event with the client custom data.

IncogniaWebSdk.sendCustomEvent({
  tag: 'test-event',
  externalId: 'external-id',
  accountId: 'account-id',
  address: {
    street: 'Main Street',
    number: '100',
    city: 'New York',
    state: 'NY',
    countryName: 'US',
    postalCode: '10001',
    addressLine: 'Main Street 100, New York, NY, US, 10001',
    latitude: 40.7486,
    longitude: -73.9864
  },
  properties: {
    string: 'string',
    number: 123,
    boolean: false
  }
})

Geolocation API

By default, the Incognia Web SDK does not ask the user for geolocation, because:

• Not all use cases requires geolocation
• The website should have total control when to ask for geolocation
• The lib should run silently.

However, if the geolocation is available (It was authorized by the user before), the Web SDK will include the geolocation information into the token.

Allowing Incognia to request geolocation permissions

When getting the requestToken, the option parameter askForGeolocation can be used to allow Incognia to automatically request the user location permissions.

const requestToken = await IncogniaWebSdk.generateRequestToken({
  askForGeolocation: true
})

How and when to ask the user for geolocation?

The ideal flow to manually ask the user for geolocation is:

1. Initialize the SDK:

IncogniaWebSdk.init(...)

2. Ask the user for Geolocation and then proceed to get the token:

navigator.geolocation.getCurrentPosition(generateRequestToken, generateRequestToken)

function generateRequestToken() {
  const requestToken = await IncogniaWebSdk.generateRequestToken()
  //TODO: Send the requestToken to your backend.
}

Browser Compatibility

Except for IE, this lib is compatible with every modern browser.

However, for Geolocation API, each browser handles it differently. For example, Firefox v104 does not provide the Geolocation API by default. So the user has to enable it. Besides, for some OSs like MacOS, you have to allow the browser to access the geolocation. If the geolocation is not available, the token will be generated without that information.