The Incognia SDK for the web.
Documentation can be found at https://developer.incognia.com/docs
npm install @incognia/web-sdk
pnpm install @incognia/web-sdk
yarn add @incognia/web-sdk
Add the following script to your HTML:
<script src="https://repo.incognia.com/web/latest/incognia-web-sdk.js"></script>
Import the package:
// ES6
import IncogniaWebSdk from '@incognia/web-sdk'
// CommonJS (Outdated)
const IncogniaWebSdk = require('@incognia/web-sdk')
// CDN Script
const IncogniaWebSdk = window.IncogniaWebSdk
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>')
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()
This method generates a request token and returns it.
const requestToken = await IncogniaWebSdk.generateRequestToken()
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
}
})
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.
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
})
The ideal flow to manually ask the user for geolocation is:
1. Initialize the SDK:
IncogniaWebSdk.init(...)
- 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.
}
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.