Analytics
The SDK provides an interface that you can implement and that will be used by the SDK to send events. The interface is simply the one below:
Trace is the object passed to your implementation and you can use it with any of your analytics tools or any custom tracing mechanism. Make sure to avoid blocking calls if you push the information of the trace object to any external system.
The Trace object has the following properties:
Property | Type | Optional | Default | Description |
---|---|---|---|---|
sessionId | String | No | None | Session id (UUID v4) created by the SDK or passed by your application |
category | TraceCategory | No | None | See below |
event | TraceEvent | No | None | See below |
status | TraceStatus | No | None | See below |
page | TracePage | Yes | null | See below |
statusCode | TraceStatusCode | Yes | null | See below |
statusMessage | String | Yes | null | Description of the status code if any |
documentType | DocumentType | Yes | null | Document type |
timestamp | Date | No | Current date | Timestamp of the event |
TraceCategory has the following properties:
Property | Type | Description |
---|---|---|
SDK | Enum String | For SDK level events e.g. after has successfully initialized |
ENROLLMENT | Enum String | For events related to the enrollment flow |
LOOKUP | Enum String | For events related to the lookup flow |
FACE_SESSION | Enum String | For events related to the face session flow |
TraceEvent has following properties:
Property | Type | Description |
---|---|---|
INIT | Enum String | Event when SDK initializes |
VIEW | Enum String | Event when a screen is presented to the user. Can be used to track the screen sessions. |
START | Enum String | Event when a certain process starts, e.g. scanning of a document starts |
IN_PROGRESS | Enum String | Event during document scanning and facial recognition |
COMPLETE | Enum String | Event when any process completes, e.g. scanning of a document completes |
SKIP | Enum String | Event when a specific step is skipped, e.g. NFC |
FINISH | Enum String | Event when the overall flow is terminated |
TraceStatus has the following parameters:
Property | Type | Description |
---|---|---|
SUCCESS | Enum String | Status when an event is successful |
FAILURE | Enum String | Status when an event is not successful |
TracePage has following properties:
Property | Type | Description |
---|---|---|
SCAN | Enum String | Document scanning page |
LOOKUP | Enum String | Lookup page |
READ | Enum String | NFC chip reading page |
FACE | Enum String | Facial recognition page |
BACKGROUND_CHECK | Enum String | Background check page |
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 phones, which may send different numbers of events.
Property | Type | Description |
---|---|---|
USER_CANCEL | Enum String | Status defined when user cancels the flow, or user declines the background check or users stops the chip reading process (only iOS) |
SESSION_EXPIRED | Enum String | Flow terminates because the session expires, e.g. auth token not valid anymore |
UNEXPECTED_ERROR | Enum String | Flow terminates because of an unexpected error |
SCAN_DOCUMENT_FRONT_BACK_MISMATCH | Enum String | 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. |
SCAN_DOCUMENT_NOT_RECOGNIZED | Enum String | When scanning fails because either the wrong document type is selected or not able to read data due to lighting conditions. |
SCAN_DOCUMENT_EXPIRED | Enum String | When scanning an expired document |
SCAN_DOCUMENT_FRONT_PROCESSED | Enum String | Front of the document was successfully scanned |
SCAN_DOCUMENT_BACK_PROCESSED | Enum String | Back of the document was successfully scanned |
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_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_SCREEN_DETECTED | Enum String | Screen detected (Available only if not disabled with the option allowNonPhysicalDocuments()) |
SCAN_DOCUMENT_ID_PHOTO_TAMPERING_DETECTED | Enum String | ID photo tampering detected (Available only if not disabled with the option disableTamperingRejection()) |
READ_DOCUMENT_DISCONNECTED | Enum String | When the document is removed from the device when chip reading is in progress. |
READ_AUTHENTICATION_FAILED | Enum String | When the chip authentication fails because of the OCR’d data in scanning step weren’t correct |
READ_NFC_UNAVAILABLE | Enum String | When reading is enabled but not forced and the device doesn’t support NFC. The step gets skipped, event SKIP |
READ_NFC_DOCUMENT_NOT_SUPPORTED | Enum String | When reading is enabled and forceReadingIfSupported is enabled and the document does not support NFC. The step gets skipped, event SKIP |
FACE_LIVENESS_FAILED | Enum String | When liveness detection fails during facial recognition |
FACE_NO_MATCH | Enum String | When face doesn’t match the picture provided with the document, or from the chip if available, during facial recognition |
FACE_TIMEOUT | Enum String | When not user face or no face motion is detected during the facial recognition process |
READ_DOCUMENT_VALIDATION_FAILED | Enum String | Session gets invalidated because the CHIP validation of the card fails, and the reading step is forced by configuration |
READ_CHIP_VALIDATION_FAILED | Enum String | Session gets invalidated because the document doesn’t support reading (e.g. no chip available) and the reading step is forced by configuration |
FACE_RECOGNITION_TOO_MANY_ATTEMPTS | Enum String | Session gets invalidated because of too many failed facial recognition attempts |
FACE_INCORRECT_POSITION_DETECTED | Enum String | Incorrect face position detected |
FACE_INCORRECT_DISTANCE_DETECTED | Enum String | Incorrect face distance 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 (Available only if not disabled with the option allowClosedEyes()) |
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 |
LOOKUP_ID_NOT_FOUND | Enum String | ID not found based on the information provided by the end user |
LOOKUP_INVALID_INPUT | Enum String | ID not found based or wrong information provided by the end user |
LOOKUP_OTP_TOO_MANY_ATTEMPTS | Enum String | Session gets invalidated because of too many failed OTP attempts |
CAMERA_NOT_AVAILABLE | Enum String | Session gets invalidated because the camera is not available |
CAMERA_PERMISSION_NOT_GRANTED | Enum String | Session gets invalidated because camera the end user denies camera access |
To enable the tracing mechanism pass your implementation to the init method:
Below you can find an example of the tracing above for a full enrollment flow with some errors in between to showcase the events:
Below you can find an example on how to use the trace information with Firebase Analytics:
Last updated