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:

interface Tracer {
   fun trace(trace: Trace)
}

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:

PropertyTypeOptionalDefaultDescription

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:

PropertyTypeDescription

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:

PropertyTypeDescription

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

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:

PropertyTypeDescription

SUCCESS

Enum String

Status when an event is successful

FAILURE

Enum String

Status when an event is not successful

TracePage has following properties:

PropertyTypeDescription

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:

PropertyTypeDescription

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

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

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:

class App: Application() {

	override fun onCreate() {
    	    super.onCreate()
    	    UqudoSDK.init(applicationContext, TracerObject)
  	}

  	private object TracerObject : Tracer {
          override fun trace(trace: Trace) {
              Logger.d("---Analytics", trace.toString())
          }
      }

}

Below you can find an example of the tracing above for a full enrollment flow with some errors in between to showcase the events:

2021-02-04 09:42:38.632 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=, category=SDK, event=INIT, status=SUCCESS, page=null, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:37:38 GMT+07:00 2021)
2021-02-04 09:42:39.117 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=VIEW, status=SUCCESS, page=SCAN, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:42:39 GMT+07:00 2021)
2021-02-04 09:42:45.798 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=SCAN, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:42:45 GMT+07:00 2021)
2021-02-04 09:42:52.749 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=FAILURE, page=SCAN, statusCode=SCAN_DOCUMENT_NOT_RECOGNIZED, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:42:52 GMT+07:00 2021)
2021-02-04 09:42:53.736 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=SCAN, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:42:53 GMT+07:00 2021)
2021-02-04 09:43:03.767 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=SUCCESS, page=SCAN, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:03 GMT+07:00 2021)
2021-02-04 09:43:03.871 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=VIEW, status=SUCCESS, page=READ, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:03 GMT+07:00 2021)
2021-02-04 09:43:07.090 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=READ, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:07 GMT+07:00 2021)
2021-02-04 09:43:39.553 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=FAILURE, page=READ, statusCode=READ_DOCUMENT_DISCONNECTED, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:39 GMT+07:00 2021)
2021-02-04 09:43:49.216 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=READ, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:49 GMT+07:00 2021)
2021-02-04 09:43:58.540 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=SUCCESS, page=READ, statusCode=null, statusMessage=null, documentType=PASSPORT, timestamp=Thu Feb 04 09:43:58 GMT+07:00 2021)
2021-02-04 09:43:58.652 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=VIEW, status=SUCCESS, page=FACE, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:43:58 GMT+07:00 2021)
2021-02-04 09:44:05.316 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=FACE, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:05 GMT+07:00 2021)
2021-02-04 09:44:11.319 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=FAILURE, page=FACE, statusCode=FACE_TIMEOUT, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:11 GMT+07:00 2021)
2021-02-04 09:44:15.984 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=FACE, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:15 GMT+07:00 2021)
2021-02-04 09:44:30.253 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=FAILURE, page=FACE, statusCode=FACE_TIMEOUT, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:30 GMT+07:00 2021)
2021-02-04 09:44:35.222 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=FACE, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:35 GMT+07:00 2021)
2021-02-04 09:44:42.707 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=SUCCESS, page=FACE, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:42 GMT+07:00 2021)
2021-02-04 09:44:42.921 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=VIEW, status=SUCCESS, page=BACKGROUND_CHECK, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:42 GMT+07:00 2021)
2021-02-04 09:44:48.973 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=START, status=SUCCESS, page=BACKGROUND_CHECK, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:48 GMT+07:00 2021)
2021-02-04 09:44:49.853 18994-19168/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=COMPLETE, status=SUCCESS, page=BACKGROUND_CHECK, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:49 GMT+07:00 2021)
2021-02-04 09:44:51.061 18994-19190/io.uqudo.demo D/---Analytics: Trace(sessionId=fd86bab1-7b95-4f0e-a6ba-d5322c4a19e2, category=ENROLLMENT, event=FINISH, status=SUCCESS, page=null, statusCode=null, statusMessage=null, documentType=null, timestamp=Thu Feb 04 09:44:51 GMT+07:00 2021)

Below you can find an example on how to use the trace information with Firebase Analytics:

class App: Application() {

  private lateinit var firebaseAnalytics: FirebaseAnalytics

  override fun onCreate() {
    super.onCreate()

    firebaseAnalytics = Firebase.analytics
    UqudoSDK.init(applicationContext, TracerObject(firebaseAnalytics))
  }

  private class TracerObject constructor(private val firebaseAnalytics: FirebaseAnalytics) : Tracer {
    override fun trace(trace: Trace) {
       firebaseAnalytics.logEvent(trace.category.name) {
           param("sessionId", trace.sessionId)
           param("event", trace.event.name)
           param("status", trace.status.name)
           param("timestamp", trace.timestamp.toString())
           trace.page?.let { param("page", it.name) }
           trace.statusCode?.let { param("statusCode", it.name) }
           trace.documentType?.let { param("documentType", it.name) }
           trace.statusMessage?.let { param("statusMessage", it) }
       }

       if(trace.event == TraceEvent.VIEW) {
           firebaseAnalytics.logEvent(FirebaseAnalytics.Event.SCREEN_VIEW) {
               param(FirebaseAnalytics.Param.SCREEN_NAME, trace.page?.name!!)
               param(FirebaseAnalytics.Param.SCREEN_CLASS, trace.page?.name!!)
           }

       }
    }
  }

Last updated