# Analytics

The SDK offers a callback function that you can implement, which the SDK will then use to send events.

```typescript
onTrace: (trace) => {
  console.debug("trace callback function ", trace);
}
```

Trace is the object passed to your callback function and you can use it with any of your analytics tools or any custom tracing mechanism.

Trace is the object passed to your callback function and has the following properties (see **index.d.ts** of the SDK module for details):

<table><thead><tr><th width="120">Property</th><th width="165">Type</th><th width="102">Optional</th><th width="96">Default</th><th>Description</th></tr></thead><tbody><tr><td>deviceIdentifier</td><td>String</td><td>No</td><td>None</td><td>This value uniquely identifies multiple sessions from a given device (persisting until browser local storage is cleared)</td></tr><tr><td>sessionId</td><td>String</td><td>No</td><td>None</td><td>Session id (UUID v4) created by the SDK or passed by your application</td></tr><tr><td>category</td><td>TraceCategory</td><td>No</td><td>None</td><td>See below</td></tr><tr><td>event</td><td>TraceEvent</td><td>No</td><td>None</td><td>See below</td></tr><tr><td>status</td><td>TraceStatus</td><td>No</td><td>None</td><td>See below</td></tr><tr><td>page</td><td>TracePage</td><td>Yes</td><td>null</td><td>See below</td></tr><tr><td>statusCode</td><td>TraceStatusCode</td><td>Yes</td><td>null</td><td>See below</td></tr><tr><td>statusMessage</td><td>String</td><td>Yes</td><td>null</td><td>Description of the status code if any</td></tr><tr><td>documentType</td><td>DocumentType</td><td>Yes</td><td>null</td><td>Document type</td></tr><tr><td>timestamp</td><td>Date</td><td>No</td><td>Timestamp of the event</td><td>Timestamp of the event</td></tr></tbody></table>

**TraceCategory** has the following properties:

<table><thead><tr><th width="219">Property</th><th width="127">Type</th><th>Description</th></tr></thead><tbody><tr><td>ENROLLMENT</td><td>Enum String</td><td>For events related to the enrollment flow</td></tr><tr><td>FACE_SESSION</td><td>Enum String</td><td>For events related to the face session flow</td></tr></tbody></table>

**TraceEvent** has following properties:

<table><thead><tr><th width="140">Property</th><th width="128">Type</th><th>Description</th></tr></thead><tbody><tr><td>VIEW</td><td>Enum String</td><td>Event when a screen is presented to the user. Can be used to track the screen sessions.</td></tr><tr><td>START</td><td>Enum String</td><td>Event when a certain process starts, e.g. scanning of a document starts</td></tr><tr><td>IN_PROGRESS</td><td>Enum String</td><td>Event during document scanning and facial recognition</td></tr><tr><td>COMPLETE</td><td>Enum String</td><td>Event when any process completes, e.g. scanning of a document completes</td></tr><tr><td>SKIP</td><td>Enum String</td><td>Event when a specific step is skipped. Only available in the background check step when the view is enabled, consent is enabled the the enduser declines the consent</td></tr><tr><td>FINISH</td><td>Enum String</td><td>Event when the overall flow is terminated</td></tr></tbody></table>

**TraceStatus** has the following parameters:

<table><thead><tr><th width="138">Property</th><th width="131">Type</th><th>Description</th></tr></thead><tbody><tr><td>SUCCESS</td><td>Enum String</td><td>Status when an event is successful</td></tr><tr><td>FAILURE</td><td>Enum String</td><td>Status when an event is not successful</td></tr></tbody></table>

**TracePage** has following properties:

<table><thead><tr><th width="224">Property</th><th width="153">Type</th><th>Description</th></tr></thead><tbody><tr><td>SCAN</td><td>Enum String</td><td>Document scanning page</td></tr><tr><td>FACE</td><td>Enum String</td><td>Facial recognition page</td></tr><tr><td>BACKGROUND_CHECK</td><td>Enum String</td><td>Background check page</td></tr></tbody></table>

**TraceStatusCode** has the following properties:

**Note**: Please be aware that all codes with event IN\_PROGRESS, except for SCAN\_DOCUMENT\_FRONT\_PROCESSED and SCAN\_DOCUMENT\_BACK\_PROCESSED, are throttled (limited to one identical event every 5 seconds). This is to ensure that your client is not overwhelmed and to accommodate varying speeds of different devices, which may send different numbers of events.

<table><thead><tr><th width="228">Property</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td>USER_CANCEL</td><td>Enum String</td><td>Status defined when user cancels the flow, or user declines the background check or users stops the chip reading process (only iOS)</td></tr><tr><td>SESSION_EXPIRED</td><td>Enum String</td><td>Flow terminates because the session expires, e.g. auth token not valid anymore</td></tr><tr><td>UNEXPECTED_ERROR</td><td>Enum String</td><td>Flow terminates because of an unexpected error</td></tr><tr><td>SCAN_DOCUMENT_FRONT_BACK_MISMATCH</td><td>Enum String</td><td>When scanning fails because the front and back of the document don’t match, e.g. emirates id number in the front doesn’t match the id in the MRZ in the back page.</td></tr><tr><td>SCAN_DOCUMENT_NOT_RECOGNIZED</td><td>Enum String</td><td>When scanning fails because either the wrong document type is selected or not able to read data due to lighting conditions.</td></tr><tr><td>SCAN_DOCUMENT_EXPIRED</td><td>Enum String</td><td>When scanning an expired document</td></tr><tr><td>SCAN_DOCUMENT_FRONT_PROCESSED</td><td>Enum String</td><td>Front of the document was successfully scanned</td></tr><tr><td>SCAN_DOCUMENT_BACK_PROCESSED</td><td>Enum String</td><td>Back of the document was successfully scanned</td></tr><tr><td>SCAN_DOCUMENT_AGE_VERIFICATION_FAILED</td><td>Enum String</td><td>When age is below the one defined in the configuration</td></tr><tr><td>FACE_LIVENESS_FAILED</td><td>Enum String</td><td>When liveness detection fails during facial recognition</td></tr><tr><td>FACE_NO_MATCH</td><td>Enum String</td><td>When face doesn’t match the picture provided with the document, or from the chip if available, during facial recognition</td></tr><tr><td>FACE_RECOGNITION_TOO_MANY_ATTEMPTS</td><td>Enum String</td><td>Session gets invalidated because of too many failed facial recognition attempts</td></tr><tr><td>FACE_INCORRECT_POSITION_DETECTED</td><td>Enum String</td><td>Incorrect face position detected</td></tr><tr><td>FACE_INCORRECT_DISTANCE_DETECTED</td><td>Enum String</td><td>Incorrect face distance detected</td></tr><tr><td>FACE_EYES_CLOSED_DETECTED</td><td>Enum String</td><td>Eyes closed detected</td></tr><tr><td>CAMERA_NOT_AVAILABLE</td><td>Enum String</td><td>Session gets invalidated because the camera is not available</td></tr><tr><td>CAMERA_PERMISSION_NOT_GRANTED</td><td>Enum String</td><td>Session gets invalidated because camera the end user denies camera access</td></tr><tr><td>MEDIA_VIRTUAL_CAMERA_DETECTED</td><td>Enum String</td><td>Session gets invalidated because virtual camera usage was detected</td></tr></tbody></table>

**Note**: The status codes listed below are available only from SDK 4.x and above

| Property                                          | Type        | Description                                                                                                                                                                                                                                                                                      |
| ------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| SCAN\_DOCUMENT\_DARK\_ENVIRONMENT\_DETECTED       | Enum String | Dark environment detected                                                                                                                                                                                                                                                                        |
| SCAN\_DOCUMENT\_INCORRECT\_DISTANCE\_DETECTED     | Enum String | Incorrect distance detected between the camera and the document                                                                                                                                                                                                                                  |
| SCAN\_DOCUMENT\_INCORRECT\_POSITION\_DETECTED     | Enum String | Incorrect position detected, e.g. document positioned too on the top or the bottom of the screen                                                                                                                                                                                                 |
| SCAN\_DOCUMENT\_BLUR\_DETECTED                    | Enum String | Blur or noisy image detected                                                                                                                                                                                                                                                                     |
| SCAN\_DOCUMENT\_INCORRECT\_TYPE\_DETECTED         | Enum String | Incorrect document type dected, e.g. presenting another document type                                                                                                                                                                                                                            |
| SCAN\_DOCUMENT\_INCORRECT\_SIDE\_DETECTED         | Enum String | Incorrect document side dected, e.g. presenting the back of the document instead of the front side                                                                                                                                                                                               |
| SCAN\_DOCUMENT\_GLARE\_DETECTED                   | Enum String | Reflections detected on the document                                                                                                                                                                                                                                                             |
| SCAN\_DOCUMENT\_ID\_PHOTO\_BAD\_QUALITY\_DETECTED | Enum String | ID photo on the document is not clear                                                                                                                                                                                                                                                            |
| SCAN\_DOCUMENT\_FINGER\_DETECTED                  | Enum String | Fingers are obstructing the document                                                                                                                                                                                                                                                             |
| FACE\_MULTIPLE\_FACES\_DETECTED                   | Enum String | Multiple faces detected during facial recognition                                                                                                                                                                                                                                                |
| FACE\_INCORRECT\_DISTANCE\_DETECTED               | Enum String | Incorrect face distance detected                                                                                                                                                                                                                                                                 |
| FACE\_INCORRECT\_POSITION\_DETECTED               | Enum String | Incorrect face position detected                                                                                                                                                                                                                                                                 |
| FACE\_DARK\_ENVIRONMENT\_DETECTED                 | Enum String | Dark environment detected                                                                                                                                                                                                                                                                        |
| FACE\_BLUR\_DETECTED                              | Enum String | Blur or noisy image detected                                                                                                                                                                                                                                                                     |
| FACE\_MOUTH\_COVER\_DETECTED                      | Enum String | Mouth covered detected                                                                                                                                                                                                                                                                           |
| FACE\_EYES\_COVER\_DETECTED                       | Enum String | Eyes covered detected                                                                                                                                                                                                                                                                            |
| FACE\_EYES\_CLOSED\_DETECTED                      | Enum String | Eyes closed detected                                                                                                                                                                                                                                                                             |
| FACE\_SPOTLIGHT\_DETECTED                         | Enum String | Bright spotlight on the face detected                                                                                                                                                                                                                                                            |
| FACE\_SHADOW\_DETECTED                            | Enum String | Shadow on the face detected                                                                                                                                                                                                                                                                      |
| FACE\_EYES\_SHADOW\_DETECTED                      | Enum String | Shadow on the eyes detected                                                                                                                                                                                                                                                                      |
| VIDEO\_PLAYS\_INLINE\_DISABLED                    | Enum String | It’s returned when HTML5 videos default to the native full-screen player instead of playing inline, something that only occurs when the SDK is embedded in an iOS WebView with `allowsInlineMediaPlayback` set to `false`. This status code helps you identify and correct your WebView settings |
| WASM\_LOAD\_FAILED                                | Enum String | When the SDK drops the session after failing to load the WASM module most probably because of network issues                                                                                                                                                                                     |
| WASM\_NOT\_SUPPORTED                              | Enum String | When the SDK drops the session because the browser doesn't support the basic feature to run the WASM module                                                                                                                                                                                      |