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 UQTracer : NSObject
- (void)trace:(UQTrace *)trace;
@end

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 UQTrace object has the following properties:

Property	Type	Optional	Default
sessionId	String	No	None	Session id (UUID v4) created by the SDK or passed by your application
category	UQTraceCategory	No	None	See below
event	UQTraceEvent	No	None	See below
status	UQTraceStatus	No	None	See below
page	UQTracePage	Yes	null	See below
statusCode	UQTraceStatusCode	Yes	null	See below
statusMessage	String	Yes	null	Description of the status code if any
documentType	DocumentTypeID	Yes	null	Document type id
timestamp	Date	No	Current date	Timestamp of the event

UQTraceCategory has the following properties:

Property	Type	Description
Property	Type	Description
TC_SDK	Enum String	For SDK level events e.g. after has successfully initialized
TC_ENROLLMENT	Enum String	For events related to the enrolment flow
TC_LOOKUP	Enum String	For events related to the lookup flow
TC_FACE_SESSION	Enum String	For events related to the face session flow

UQTraceEvent has following properties:

Property	Type	Description
TE_INIT	Enum String	Event when SDK initializes
TE_VIEW	Enum String	Event when a screen is presented to the user. Can be used to track the screen sessions.
TE_START	Enum String	Event when a certain process starts, e.g. scanning of a document starts
TE_IN_PROGRESS	Enum String	Event during document scanning and facial recognition
TE_COMPLETE	Enum String	Event when any process completes, e.g. scanning of a document completes
TE_SKIP	Enum String	Event when a specific step is skipped, e.g. NFC
TE_FINISH	Enum String	Event when the the overall flow is terminated

UQTraceStatus has the following parameters:

Property	Type	Description
TS_SUCCESS	Enum String	Status when an event is successful
TS_FAILURE	Enum String	Status when an event is not successful

UQTracePage has following properties:

Property	Type	Description
TP_SCAN	Enum String	Document scanning page
TP_LOOKUP	Enum String	Lookup page
TP_READ	Enum String	NFC chip reading page
TP_FACE	Enum String	Facial recognition page
TP_BACKGROUND_CHECK	Enum String	Background check page

UQTraceStatusCode 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
TSC_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)
TSC_SESSION_EXPIRED	Enum String	Flow terminates because the session expires, e.g. auth token not valid anymore
TSC_UNEXPECTED_ERROR	Enum String	Flow terminates because of an unexpected error
TSC_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.
TSC_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.
TSC_SCAN_DOCUMENT_EXPIRED	Enum String	When scanning an expired document
TSC_SCAN_DOCUMENT_FRONT_PROCESSED	Enum String	Front of the document was successfully scanned
TSC_SCAN_DOCUMENT_BACK_PROCESSED	Enum String	Back of the document was successfully scanned
TSC_SCAN_DOCUMENT_DARK_ENVIRONMENT_DETECTED	Enum String	Dark environment detected
TSC_SCAN_DOCUMENT_INCORRECT_DISTANCE_DETECTED	Enum String	Incorrect distance detected between the camera and the document
TSC_SCAN_DOCUMENT_BLUR_DETECTED	Enum String	Blur or noisy image detected
TSC_SCAN_DOCUMENT_INCORRECT_TYPE_DETECTED	Enum String	Incorrect document type dected, e.g. presenting another document type
TSC_SCAN_DOCUMENT_INCORRECT_SIDE_DETECTED	Enum String	Incorrect document side dected, e.g. presenting the back of the document instead of the front side
TSC_SCAN_DOCUMENT_GLARE_DETECTED	Enum String	Reflections detected on the document
TSC_SCAN_DOCUMENT_ID_PHOTO_BAD_QUALITY_DETECTED	Enum String	ID photo on the document is not clear
TSC_SCAN_DOCUMENT_SCREEN_DETECTED	Enum String	Screen detected (Available only if not disabled with the option allowNonPhysicalDocuments=True)
TSC_SCAN_DOCUMENT_PRINT_DETECTED	Enum String	Print detected (Available only if not disabled with the option allowNonPhysicalDocuments=True)
TSC_SCAN_DOCUMENT_ID_PHOTO_TAMPERING_DETECTED	Enum String	ID photo tampering detected (Available only if not disabled with the option disableTamperingRejection=True)
TSC_READ_DOCUMENT_DISCONNECTED	Enum String	When the document is removed from the device when chip reading is in progress.
TSC_READ_AUTHENTICATION_FAILED	Enum String	When the chip authentication fails because of the OCR data in scanning step weren’t correct
TSC_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
TSC_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
TSC_FACE_LIVENESS_FAILED	Enum String	When liveness detection fails during facial recognition
TSC_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
TSC_FACE_TIMEOUT	Enum String	When not user face or no face motion is detected during the facial recognition process
TSC_FACE_INCORRECT_POSITION_DETECTED	Enum String	Incorrect face position detected
TSC_FACE_INCORRECT_DISTANCE_DETECTED	Enum String	Incorrect face distance detected
TSC_FACE_DARK_ENVIRONMENT_DETECTED	Enum String	Dark environment detected
TSC_FACE_BLUR_DETECTED	Enum String	Blur or noisy image detected
TSC_FACE_MOUTH_COVER_DETECTED	Enum String	Mouth covered detected
TSC_FACE_EYES_COVER_DETECTED	Enum String	Eyes covered detected
TSC_FACE_EYES_CLOSED_DETECTED	Enum String	Eyes closed detected (Available only if not disabled with the option allowClosedEyes=True)
TSC_FACE_SPOTLIGHT_DETECTED	Enum String	Bright spotlight on the face detected
TSC_FACE_SHADOW_DETECTED	Enum String	Shadow on the face detected
TSC_FACE_EYES_SHADOW_DETECTED	Enum String	Shadow on the eyes detected
TSC_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
TSC_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
TSC_FACE_RECOGNITION_TOO_MANY_ATTEMPTS	Enum String	Session gets invalidated because of too many failed facial recognition attempts
TSC_LOOKUP_INVALID_INPUT	Enum String	ID not found based on the information provided by the end user
TSC_LOOKUP_ID_NOT_FOUND	Enum String	ID not found based or wrong information provided by the end user
TSC_LOOKUP_OTP_TOO_MANY_ATTEMPTS	Enum String	Session gets invalidated because of too many failed OTP attempts
TSC_CAMERA_NOT_AVAILABLE	Enum String	Session gets invalidated because the camera is not available
TSC_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 like the example below. Even in a Swift project you have to write the implementation in Objective-C. You can then decide to follow up with Swift passing the trace data from objective c to Swift.

Tracer implementation example:

Objective-C

@implementation UQTracer

- (void)trace:(UQTrace *)trace {
    NSString *documentTypeName = @"";
    if (trace.documentType != UNSPECIFY) {
        UQDocumentConfig *document = [[UQDocumentConfig alloc] initWithDocumentType:trace.documentType];
        documentTypeName = document.documentName;
    }
    NSString *timeStamp = [self timeStamp:trace.timestamp];
    NSLog(@"Trace(sessionId=%@, category=%@, event=%@, page=%@, status=%@, statusCode=%@, statusMessage=%@, documentType=%@, timestamp=%@)" , trace.sessionId, trace.category->name, trace.event->name, trace.page->name ,trace.status->name, trace.statusCode->name, trace.statusMessage, documentTypeName, timeStamp);
}

- (NSString *)timeStamp:(NSDate *)currentDate {
    return [NSDateFormatter localizedStringFromDate:currentDate
                                            dateStyle:NSDateFormatterFullStyle
                                            timeStyle:NSDateFormatterFullStyle];
}
@end

Tracer implementation example passing the trace data to Swift (the example below assumes that you have the SwiftTracer object defined in your Swift project with method signature trace):

Objective-C

@interface UQTracer ()
@property (nonatomic) SwiftTracer *swiftTracer;
@end

@implementation UQTracer
- (instancetype)init {
    self = [super init];
    if (self) {
        self.swiftTracer = [[SwiftTracer alloc] init];
    }
    return self;
}

- (void)trace:(UQTrace *)trace {
    NSString *documentTypeName = @"";
    if (trace.documentType != UNSPECIFY) {
        UQDocumentConfig *document = [[UQDocumentConfig alloc] initWithDocumentType:trace.documentType];
        documentTypeName = document.documentName;
    }

    [self.swiftTracer     traceWithSessionId:trace.sessionId
                                    category:trace.category->name
                                       event:trace.event->name
                                      status:trace.status->name
                                        page:trace.page->name
                                  statusCode:trace.statusCode->name
                               statusMessage:trace.statusMessage
                                    document:documentTypeName
                                   timestamp:trace.timestamp];
}
@end

Initialize SDK with tracer in Objective-C:

Objective-c

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application willFinishLaunchingWithOptions:(NSDictionary<UIApplicationLaunchOptionsKey,id> *)launchOptions {
    UQTracer *tracer = [[UQTracer alloc] init];
    [[UQBuilderController alloc] initWithTracer:tracer];
    return YES;
}
@end

Initialize SDK with tracer in Swift:

Swift

class AppDelegate: UIResponder, UIApplicationDelegate {
        
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let tracer = UQTracer()
        _ = UQBuilderController.init(tracer: tracer)
        return true
    }
}

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 23:55:52.835375+0700 UqudoSDKDemo[520:87001] Trace(sessionId=(null), category=SDK, event=INIT, page=(null), status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:55:52 Indochina Time)
2021-02-04 23:56:30.331468+0700 UqudoSDKDemo[520:87090] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=VIEW, page=SCAN, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:56:30 Indochina Time)
2021-02-04 23:56:31.270246+0700 UqudoSDKDemo[520:87090] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=SCAN, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:56:31 Indochina Time)
2021-02-04 23:56:43.938264+0700 UqudoSDKDemo[520:87259] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=SCAN, status=FAILURE, statusCode=SCAN_DOCUMENT_NOT_RECOGNIZED, statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:56:43 Indochina Time)
2021-02-04 23:56:52.071336+0700 UqudoSDKDemo[520:87279] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=SCAN, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:56:52 Indochina Time)
2021-02-04 23:57:05.886765+0700 UqudoSDKDemo[520:87280] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=SCAN, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:05 Indochina Time)
2021-02-04 23:57:05.903494+0700 UqudoSDKDemo[520:87280] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=VIEW, page=READ, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:05 Indochina Time)
2021-02-04 23:57:10.125406+0700 UqudoSDKDemo[520:87280] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=READ, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:10 Indochina Time)
2021-02-04 23:57:25.038866+0700 UqudoSDKDemo[520:87259] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=READ, status=FAILURE, statusCode=READ_DOCUMENT_DISCONNECTED, statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:25 Indochina Time)
2021-02-04 23:57:35.027795+0700 UqudoSDKDemo[520:87259] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=READ, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:35 Indochina Time)
2021-02-04 23:57:39.185936+0700 UqudoSDKDemo[520:87399] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=READ, status=FAILURE, statusCode=USER_CANCEL, statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:39 Indochina Time)
2021-02-04 23:57:42.994229+0700 UqudoSDKDemo[520:87401] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=READ, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:57:42 Indochina Time)
2021-02-04 23:58:09.691329+0700 UqudoSDKDemo[520:87752] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=READ, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=PASSPORT, timestamp=Thursday, 4 February BE 2564 23:58:09 Indochina Time)
2021-02-04 23:58:09.695761+0700 UqudoSDKDemo[520:87752] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=VIEW, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:09 Indochina Time)
2021-02-04 23:58:11.906030+0700 UqudoSDKDemo[520:87792] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:11 Indochina Time)
2021-02-04 23:58:20.427607+0700 UqudoSDKDemo[520:87752] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=FACE, status=FAILURE, statusCode=FACE_TIMEOUT, statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:20 Indochina Time)
2021-02-04 23:58:23.958376+0700 UqudoSDKDemo[520:87913] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:23 Indochina Time)
2021-02-04 23:58:32.470057+0700 UqudoSDKDemo[520:87802] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=FACE, status=FAILURE, statusCode=FACE_TIMEOUT, statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:32 Indochina Time)
2021-02-04 23:58:34.140175+0700 UqudoSDKDemo[520:87913] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:34 Indochina Time)
2021-02-04 23:58:50.816411+0700 UqudoSDKDemo[520:87924] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=FACE, status=FAILURE, statusCode=FACE_TIMEOUT, statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:50 Indochina Time)
2021-02-04 23:58:51.657288+0700 UqudoSDKDemo[520:87912] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:51 Indochina Time)
2021-02-04 23:58:58.925882+0700 UqudoSDKDemo[520:87924] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=FACE, status=FAILURE, statusCode=FACE_NO_MATCH, statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:58:58 Indochina Time)
2021-02-04 23:59:05.496069+0700 UqudoSDKDemo[520:87913] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:05 Indochina Time)
2021-02-04 23:59:17.045578+0700 UqudoSDKDemo[520:87913] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=FACE, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:17 Indochina Time)
2021-02-04 23:59:17.137647+0700 UqudoSDKDemo[520:88083] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=VIEW, page=BACKGROUND_CHECK, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:17 Indochina Time)
2021-02-04 23:59:19.777937+0700 UqudoSDKDemo[520:87924] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=START, page=BACKGROUND_CHECK, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:19 Indochina Time)
2021-02-04 23:59:21.272898+0700 UqudoSDKDemo[520:88037] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=COMPLETE, page=BACKGROUND_CHECK, status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:21 Indochina Time)
2021-02-04 23:59:22.857039+0700 UqudoSDKDemo[520:87913] Trace(sessionId=9C40E0C2-A7C2-4FF2-B0C1-C22DE3E99D18, category=ENROLLMENT, event=FINISH, page=(null), status=SUCCESS, statusCode=(null), statusMessage=(null), documentType=, timestamp=Thursday, 4 February BE 2564 23:59:22 Indochina Time)

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

Objective-C

#import <Foundation/Foundation.h>
#import <UqudoSDK/UqudoSDK.h>
@import FirebaseAnalytics;

@implementation UQTracer

- (void)trace:(UQTrace *)trace {
    NSString *timeStamp = [self timeStamp:trace.timestamp];
    NSMutableDictionary* parameters = [[NSMutableDictionary alloc] init];
    [parameters setValue:trace.event->name forKey:@"event"];
    [parameters setValue:trace.status->name forKey:@"status"];
    [parameters setValue:timeStamp forKey:@"timestamp"];
    if (trace.sessionId) {
        [parameters setValue:trace.sessionId forKey:@"sessionId"];
    }
    if (TP_NULL != trace.page) {
        [parameters setValue:trace.page->name forKey:@"page"];
    }
    if (TSC_NULL != trace.statusCode) {
        [parameters setValue:trace.statusCode->name forKey:@"statusCode"];
    }
    if (trace.documentType != UNSPECIFY) {
        UQDocumentConfig *document = [[UQDocumentConfig alloc] initWithDocumentType:trace.documentType];
        [parameters setValue:document.documentName forKey:@"documentType"];
    }
    if (trace.statusMessage) {
        [parameters setValue:trace.statusMessage forKey:@"statusMessage"];
    }
    [FIRAnalytics logEventWithName:trace.category->name parameters:parameters];
}

- (NSString *)timeStamp:(NSDate *)currentDate {
    NSISO8601DateFormatter *dateFormatter = [[NSISO8601DateFormatter alloc] init];
    return [dateFormatter stringFromDate:currentDate];
}

@end