Abee Digital Id (ADI)Core library

Model and reference implementation of the core Abee Digital Id library.

Key features

• Track user behaviour
• Compliant with user consents. When no consent is given tracking is disabled.
• Out of the box Fingerprint Provider for browser based channels
• Out of the box standarized GDPR Provider

Operating principles

Patient represents an individual whose behaviour may be tracked by the ADI. Patient may be anonimous but also when enough information is captured patient can be identified as a persona (transition from patient to persona). ADI patient id may be stored/calculated either by using cookies or by device fingerprinting activities

Persona is an identified patient, a real user not an anonymous one.

GDPR Compliance and tracking consent before patient behaviour is tracked ADI will always ask a GDPR provider for consent for tracking this particular user behaviour. Also, when ADI gets notified about real user id, it will force asking GDPR provider for consent to track user behaviour. When no such consent is given ADI will not track behaviour nor perform any other activities. As for anonymous users

Tracking context patient behaviour is always captured with two context dimensions. One is the patient itself (either anonymous or identified) the other is the context of the application that patient uses.

Adding real person context by default ADI builds anonymous profile of user but when it's possible binding between real person and ADI patient can be registered (for instance when user logs in and is identified as a result). In such case all events will be also captured in the context of the identified real user. Also when ADI is given real persona id ADI will make additional check with GDPR to make sure that it's allowed to capture this particular persona behaviour.

Usage

Initialization

Initialization options:

| Property | Type | Description | | ------------- |:-------------:| -----:| | applicationKey | string | Unique application key that identifies your channel. | | storageProvider | StorageProvider | Channel specific storage provider. Storage provider will read/write locally on the device patient data captured by ADI | | fingerprintProvider | FingerprintProvider | Channel specific device fingerprint provider. Should return at least unique device id, but may also return some additional device characteristics that will be registered as events in ADI | | gdprProvider | GDPRConsentProvider | Channel specific GDPR consent provider. For given patient data must return whether there is a consent to track patient behaviour. | | apiClient | ApiClient | Client for sending data back to ADI Core. In browser environment one may skip this option as in browsers default fetch provider will be injected as api client. | endpoint | Endpoint | ADI Core endpoint specification

Example:

  const options = {
    applicationKey: "myAppKey",
    storageProvider: storageProvider,
    fingerprintProvider: fingerprintProvider,
    gdprProvider: gdprProvider,
    apiClient: myApiClient, // for browser environemnt this one can be ommited as default browser's fetch api client will be provided
    endpoint: adiEndpoint
  }
  const patient = await adi.core.boot(options);

Registering behaviour

ADI provides out of the box set of events that capture patient behaviour.

| Event class | Event code | Description | | ------------- |:-------------:| -----:| | ADIKeyPressed | A_KP | Patient presses key. See PayloadKeyPressed for data that is captured with this event| | ADITouch | A_T | Patient touches/clicks screen/view. See PayloadTouched for data that is captured with this event| | ADIView | A_V | Patient views a view. See PayloadView for data that is captured with this event| | ADIElementView | A_EV | Patient views an element in a view. See PayloadElementView for data that is captured with this event| | ADIDeviceInfo | A_DI | Patient uses a device. See PayloadDeviceInfo for data that is captured with this event|

Generic behaviour capture sample:

  const payload = {
    // here goes event payload, according to event type
  }
  const event = new ADIKeyPressed(payload, false);
  adi.core.capture(event);

Custom events (extending base events)

One can provide custom events that are not part of the out of the box ADI setup.

New event types must inherit from ADIEventImplV1, should defne their custom payload structure and make sure that the event code do not overlap with any of the OOTB events (ADI events use the A_ prefix for built in events)

Integrating with your anti-fraud/behaviour capture backend

Integration points are provided in the adi.core.boot() options. Here are detailed information about the options:

| Argument | Type | Description | | ------------- |:-------------:| -----:| | gdprProvider | (applicationKey: string, patient: Patient, apiClient?: ApiClient):Promise<boolean> | GDPR Provider is used to check user consent to track behaviour. ADI will check for consent when necessary and will not capture any data when there is no consent. GDPR provided should return true when ADI is allowed to track user behaviour. IMPORTANT when GDPR provider does not return true ADI library will not operate. Make sure that the way the GDPR provider responds is aligned with company policy and rules especially in case of the visitor i.e. not recognized user. For such cases for ADI to operate GDPR provider shoul return true. Also when GDPR Provider is not provided at initialization ADI assumes that there is a default consent for user tracking.| |personaProvider|(applicationKey: string, patient: Patient, apiClient?: ApiClient):Promise<string\|undefined>| Persona provider is an extension point to get real user information as early as possible (not waiting for the user to log in or by any other means to bind anonymous patient/visitor with real user). It should return real user id which is called personaId or undefined when no such user was recognized. Persona provider is called when library loads and the call is performed only when there is a true response from the GDPR provider. | fingerprintProvider | (applicationKey: string, patient: Patient, apiClient?: ApiClient):Promise<Fingerprint\|string> | Fingerprint provided is used to capture device characteristics and build unique (hopefully) id of the user using these characteristics. Function should return either deviceId (when no characteristics can be returned) or the Fingerprint object that holds all the characteristics and the deviceId as well.|

Built in providers

Fingerprint provider

For browser based channels/environments ADI provides a built in device fingerprint provider.

const provider = adi.core.fingerprintProvider;
const options = {
    applicationKey: "myAppKey",
    storageProvider: storageProvider,
    fingerprintProvider: provider,
    gdprProvider: gdprProvider,    
    endpoint: adiEndpoint
  }
const patient = await adi.core.boot(options);

GDPR Provider

This is a standard implementation of a GDPR provider that will ask remote API that must be compliant with the version 1 of the gdpr-provider-api

const gdprProvider = adi.BaseGDPRProvider.getInstance({
  baseURL: "https://my.gdpr.base.url"
});
// plain usage - getting consent
const consent = await gdprProvider._gdprProvider("myapikey", patient: { journeyId: "some-journey-id"}, myApiClient);
// plain usage - setting consent
const consent = await gdprProvider._gdprProvider("myapikey", patient: { journeyId: "some-journey-id", consent: true}, myApiClient);

// using as a provider for ADI boot
const options = {
    applicationKey: "myAppKey",
    storageProvider: storageProvider,
    fingerprintProvider: fingerprintProvider,
    gdprProvider: gdprProvider.buildGDPRProvider(),
    endpoint: adiEndpoint
  }

const patient = await adi.core.boot(options);

Local Storage Storage Provider

This is a standard browser implementation of a storage provider that uses browser's local storage as a persistence layer.

let storageProvider = new adi.LocalStorageProvider()

Using in NodeJs like environment (React, Vue) - TypeScript

When using core ADI library one must provide custom ApiClient implementation as the default implementation is browser ready and uses global fetch for integration between ADI and rest of the components. ApiClient MUST be provided prior any ADI core method invocations.

Importing

  import {core, LocalStorageProvider, fingerprintProvider, BaseGDPRProvider, BaseGDPRProviderOptions, ApiClient} from "abee-adi-core"

Setup

Minimal setup

  await core.boot({
      applicationKey: "mykey",
      fingerprintProvider: fingerprintProvider,
      storageProvider: new LocalStorageProvider(),
      apiClient: new SomeMyCustomApiClient(), // for node environemt must be provided as the default api client uses browser's native fetch client,      
      endpoint: adiEndpoint
  })

Setting default fingerprint provider

  import {fingerprintProvider} from "abee-adi-core"
  await core.boot({
      applicationKey: "mykey",
      fingerprintProvider: fingerprintProvider,
      storageProvider: new LocalStorageProvider(),
      apiClient: new SomeMyCustomApiClient(), // for node environemt must be provided as the default api client uses browser's native fetch client
      endpoint: adiEndpoint
  })

Setting default storage provider provider

  import {LocalStorageProvider} from "abee-adi-core"
  await core.boot({
      applicationKey: "mykey",
      fingerprintProvider: fingerprintProvider,
      storageProvider: new LocalStorageProvider(),
      apiClient: new SomeMyCustomApiClient(), // for node environemt must be provided as the default api client uses browser's native fetch client
      endpoint: adiEndpoint
  })

Setting default gdpr provider provider

  import {BaseGDPRProvider, BaseGDPRProviderOptions} from "abee-adi-core"
  const gdprProvider = BaseGDPRProvider.getInstance({
      baseURL: "https://my.base.url"
  })

  await core.boot({
      applicationKey: "mykey",
      fingerprintProvider: fingerprintProvider,
      storageProvider: new LocalStorageProvider(),
      gdprProvider: gdprProvider.buildGDPRProvider,
      apiClient: new SomeMyCustomApiClient(), // for node environemt must be provided as the default api client uses browser's native fetch client()                 
      endpoint: adiEndpoint               
  })

Using in Browser like environment (UMD/ESM module)

When used in mobile/web/pwa/spa (browser based) Abee ADI is available at the global adi window property. It's the entry point for the whole module.

Add ADI in page HEAD section

<script src="https://cdn.jsdelivr.net/npm/abee-adi-core"></script>

Using default Storage Provider

let storageProvider = new adi.LocalStorageProvider()

Using default GDPR Provider

let gdprProvider = adi.BaseGDPRProvider
  .getInstance({ baseURL:"https://base.url"})
  .buildGDPRProvider()

Using default Fingerprint provider

let fingerprintProvider = adi.fingerprintProvider;

Setting all up

To initialize adi use adi.core.boot()

adi.core
  .boot({
    applicationKey: "myApp", 
    storageProvider: storageProvider, 
    fingerprintProvider: 
    adi.fingerprintProvider,
    endpoint: adiEndpoint
  })
  .then(patient=>{console.log(patient)})