Advanced settings

Introduction

This section expands on the general information about the SDK launch.

---

Advanced information about the SDK launch

This section expands the information in the "Simplified Launch of the SDK" section.

Add private repository

For security and maintenance reasons, the new components of the SDKMobile are stored in private repositories that require specific credentials to access them. You must obtain those credentials through the support team from Facephi.

Once the credentials have been obtained, the following code snippet must be included to configure the Maven repository in the Gradle of your project, or in the file settings.gradle for it. It is recommended to include it after mavenCentral()

maven {
    Properties props = new Properties()
    def propsFile = new File('local.properties')
    if(propsFile.exists()){
        props.load(new FileInputStream(propsFile))
    }
    name="external"
    url = uri("https://facephicorp.jfrog.io/artifactory/maven-pro-fphi")
    credentials {
        username = props["artifactory.user"] ?: System.getenv("USERNAME_ARTIFACTORY")
        password = props["artifactory.token"] ?: System.getenv("TOKEN_ARTIFACTORY")
    }
}

For the project to correctly retrieve the dependencies, the credentials (Username and Token) must be correctly configured

There are several ways to configure the repository access credentials:

• As environment variables with the following names. For example:

  export USERNAME_ARTIFACTORY=YOUR_CREDENTIALS_USERNAME
  export TOKEN_ARTIFACTORY=YOUR_CREDENTIALS_TOKEN

  If the dependencies are not recognized when syncing, they must be included through environment variables in the file:

~/.zshrc

• Included in the file local.properties with the following structure:

  artifactory.user=YOUR_CREDENTIALS_USERNAME
  artifactory.token=YOUR_CREDENTIALS_TOKEN

SDK Initialization

You should avoid initializing a controller that will not be used.

The SDK works through a main controller (SDKController) that must be initialized correctly in order to use the rest of the functionality. The steps to follow in the initialization are:

1. Include the Application object through the SdkApplication class.

2. Decide whether the license will be included through a String or with a remote licensing service (see section 3.1).

3. The controller TrackingController if you want to connect to the platform.

The point 3 is optional, and would require using the Tracking component (more information about this module in its own documentation).

An example of initialization without TrackingController would be the following:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE")
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

An example of initialization with TrackingController would be the following:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE"),
    trackingController = TrackingController(),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

License injection

As mentioned previously, there are currently two ways to inject the license:

a. Obtaining the license through a service

Through a service that will simply require a URL and an API-KEY as an identifier. This would avoid problems when handling the license, as well as the constant replacement of those licenses when a problem arises with it (corruption or improper modification, license expiration...)

Example implementation in Kotlin:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOnline(EnvironmentLicensingData(
            apiKey = "...")
      )),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Example implementation in Java:

SDKController.INSTANCE.initSdk(
    new SdkApplication(activity.getApplication()),
    new LicensingOnline(new EnvironmentLicensingData(
      apiKey = "...")),
    sdkResult ->
    {
      if (sdkResult instanceof SdkResult.Success) {
        Napier.d("APP: INIT SDK: OK")
      } else if (sdkResult instanceof SdkResult.Error) {
        Napier.d("APP: INIT SDK: KO - ${it.error}")
      }
    }
  );

b. Injecting the license as a String

The license can be assigned directly as a String, as follows:

Example implementation in Kotlin:

val sdkConfig = SdkConfigurationData(
    sdkApplication = SdkApplication(application),
    licensing = LicensingOffline("LICENSE"),
)

val result = SDKController.initSdk(sdkConfig)

when (result) {
  is SdkResult.Success -> Napier.d("APP: INIT SDK: OK")
  is SdkResult.Error -> Napier.d(
          "APP: INIT SDK: KO - ${result.error.name}"
        )
}

Example implementation in Java:

SDKController.INSTANCE.initSdk(
  new SdkApplication(activity.getApplication()),
  new LicensingOffline("LICENSE"),
  sdkResult ->
  {
    if (sdkResult instanceof SdkResult.Success) {
      Timber.d("APP: INIT SDK: OK")
    } else if (sdkResult instanceof SdkResult.Error) {
      Timber.d("APP: INIT SDK: KO - ${it.error}")
    }
  }
);

Error handling

In the error part, we will have the SdkError class.

List of errors:

• EMPTY_LICENSE: Empty license

• INIT_AI_MODELS(error: String): Error obtained in the model download service

• INIT_FLOW (error: String): Error obtained in the flow download service

• LICENSE_CHECKER_ERROR (error: String): Error obtained when verifying whether the license is correct

• LICENSING_ERROR (error: String): Error obtained in the license download service

• NETWORK_CONNECTION_ERROR: Internet connection error

• TRACKING_ERROR (error: String): Error obtained when starting the Tracking controller

---

Start new operation

Whenever you want to start the flow of a new operation (examples of operations would be: onboarding, authentication, videoCall,...) it is essential to indicate to the SDKController that it is about to begin, and thus the SDK will know that the next calls to Components (also called Steps) will be part of that operation.

When starting a process or flow, always the method call must be made newOperation

This method has the following input parameters:

1. operationType: Indicates whether an ONBOARDING or AUTHENTICATION process will be performed.

2. customerId: Unique user ID, if available (controlled at application level)

   1. This parameter will appear reflected for each operation in the platform.

3. steps: List of operation steps if they have been defined beforehand

4. enableTracking: Allows enabling or disabling the sending of tracking events for this operation. If not specified, it is considered true.

There are 2 ways to perform this operation start, depending on whether the steps are known that will make up the registration or authentication process flow (in case the components are executed sequentially and always in the same way) or, otherwise, if the flow is not defined and is unknown (for example, the end customer is the one who decides the execution order of the components).

• Flow known (the operation will appear tracked in the platform with all the steps in the list).

  Example Kotlin implementation:

val result = SDKController.newOperation(
        operationType = OperationType.ONBOARDING,
        customerId = "customer_id",
        steps = listOf(Step.SELPHI_COMPONENT, Step.SELPHID_COMPONENT),
        enableTracking = true)
when (result) {
    is SdkResult.Success -> {
        Timber.d("APP: NEW OPERATION OK")
        Timber.d("Session ID: ${result.data.sessionId}")
        Timber.d("Operation ID: ${result.data.operationId}")
    }
    is SdkResult.Error -> {
        Timber.d("APP: NEW OPERATION ERROR: ${result.error.name}")
    }
}

Example Java implementation:

 SDKController.INSTANCE.newOperation(
        OperationType.ONBOARDING,
        "customer_id",
        [Step.SELPHI_COMPONENT, Step.SELPHID_COMPONENT]
        ){
          if (sdkResult instanceof SdkResult.Success) {
            Napier.d("APP: NEW OPERATION: OK")
          } else if (sdkResult instanceof SdkResult.Error) {
            Napier.d("APP: NEW OPERATION: KO - ${it.error}")
          }
        }
  );

• Flow unknown (the operation will appear tracked in the platform with ellipses). Example Kotlin implementation:

val result = SDKController.newOperation(
        operationType = OperationType.ONBOARDING,
        customerId = "customer_id",
        enableTracking = true)
when (result) {
    is SdkResult.Success -> {
        Timber.d("APP: NEW OPERATION OK")
    }
    is SdkResult.Error -> {
        Timber.d("APP: NEW OPERATION ERROR: ${result.error.name}")
    }
}

Example Java implementation:

 SDKController.INSTANCE.newOperation(
        OperationType.ONBOARDING,
        "customer_id"
        ){
          if (sdkResult instanceof SdkResult.Success) {
            Napier.d("APP: NEW OPERATION: OK")
          } else if (sdkResult instanceof SdkResult.Error) {
            Napier.d("APP: NEW OPERATION: KO - ${it.error}")
          }
        }
  );

sdkResult → Contains in data the information about the created operation.

When the result is correct, data is a OperationResult with:

Field	Description
sessionId	Identifier of the session created or retrieved by the SDK.
operationId	Identifier of the active operation.
type	Type of operation started (ONBOARDING or AUTHENTICATION).
customerId	User identifier associated with the operation.

Once the operation has been created the SDK components associated with this operation can be executed. Consult the specific documentation for each component to learn how to do it.

Existing operation types

Currently, the following operations exist, during which certain Components (STEPS).

The following table shows the relationship between operations and steps:

Operation (OperationType)	Component (Step)	Description
ONBOARDING	SELPHI_COMPONENT SELPHID_COMPONENT	- Facial validation of a selfie against the face on a document - Extraction of the document's OCR - Liveness detection
AUTHENTICATION	SELPHI_COMPONENT	- Facial validation using templates - Liveness detection

This list will be expanded in future SDK updates, as new components and use cases appear.

If the creation of a new operation returns an error of type INTERNAL_ERROR it is mainly due to a security. To investigate the cause, it is possible to retrieve the Token associated with the error, which provides additional information for analysis.

if (result.error is SdkError.INTERNAL_ERROR){
    val token = (result.error as SdkError.INTERNAL_ERROR).error
}

---

Security

The Android SDK includes a security system designed to detect and block potentially untrusted environments or those that may indicate attack attempts.

This mechanism is enabled by default, allows identifying situations that could compromise security, and prevents the SDK from running in contexts that are not considered secure:

SDKController.securityMode(enable: Boolean) 

---

Component launch

The SDK functionality is divided into different components with specific controllers. These controllers will be "launched" from the general controller.

Once the new operation (section 3), the different SDK controllers can be launched. To consult this information, you must access the documentation for each of the specific components.

Example Kotlin launch:

val result = SDKController.launch(ExampleController(ConfigurationData()))
when (result) {
    is SdkResult.Success -> {
        //Result OK
        result.data
    }
    is SdkResult.Error -> {
        //Result KO
        result.error.name
    }
}

Example Java launch:

SDKController.INSTANCE.launch(
    new ExampleController(new ConfigurationData()) {
        if (sdkResult instanceof SdkResult.Success) {
            //Result OK
            it.data
          } else if (sdkResult instanceof SdkResult.Error) {
            //Result KO
            it.error.name
          }
    }
)

Options for component launch

Once the SDK has been started and a new operation has been created, the component can be launched. There are two ways to launch the component:

• [WITH TRACKING] This call allows the component functionality to be launched normally, but internal events will be tracked to the server of tracking:

val response = SDKController.launch(
    ExampleController(SConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

• [WITHOUT TRACKING] This call allows the component functionality to be launched normally, but nothing will be tracked to the server of tracking:

val response = SDKController.launchMethod(
    ExampleController(ConfigurationData(...))
)
when (response) {
    is SdkResult.Error -> Napier.d("ERROR - ${response.error.name}")
    is SdkResult.Success -> response.data
}

The method launch must be used by default. This method allows using tracking it if its component is enabled, and it will not be used when it is disabled (or the component is not installed).

On the other hand, the method launchMethod covers a special case in which the integrator has Tracking installed and enabled, but in a specific flow within the application does not want to track information. In that case, this method is used to prevent that information from being sent to the platform.

---

Result return

The result of each component will be returned through the SDK, always maintaining the same structure through the class SdkResult whose class is a Sealed Class that can have 2 possible states:

• SdkResult.Success: Indicates that the operation has completed correctly and inside it contains:

  • data: Contains the data type needed according to the process/component launched.

• SdkResult.Error

  • error: Contains the error type needed according to the process/component launched.

The documentation for each specific component will break down the different fields that this object can return

Usage example:

when (result) {
    is SdkResult.Success -> {
        Napier.d("Selphi: OK")
        // SelphiResult:
        // result.data.bestImage
    }

    is SdkResult.Error -> Napier.d("Selphi: KO - ${result.error.name}")
}

---

Auxiliary controllers

This section includes other controllers and auxiliary operations, some of them optional, and which may be necessary for the proper completion of the Flow.

These fields are necessary for communication with the Facephi, in case you want to perform any verification and want to perform the tracking of a specific operation.

Obtaining the OperationId

val result = SDKController.launch(GetOperationIdController())
Napier.d("Operation ID ${result}")

Obtaining the OperationType

val result = SDKController.launch(GetOperationTypeController())
Napier.d("Operation type ${result}")

Obtaining the SessionId

val result = SDKController.launch(GetSessionIdController())
Napier.d("Session ID ${result}")

Obtaining the CustomerID

val result = SDKController.launch(GetCustomerIdController())
Napier.d("Customer ID ${result}")

Assigning the CustomerID

SDKController.launch(CustomerIdController("CustomerId"))

---

Debug options and error handling

There are certain options in the SDK that allow for increased debug logs so you can verify that everything is working correctly.

Error handling in Tracking connections with the platform

Once the SDK has been started correctly, certain adjustments can be applied to obtain more information about possible tracking errors; monitoring can be performed through this controller launch:

SDKController.launch(TrackingErrorController {
    Napier.d("Tracking Error: ${it.name}")
})

Enabling general debug logs

 if (BuildConfig.DEBUG) {
  SDKController.enableDebugMode()
 }

---

Tracking and Analysis of Events in the Application

The event functionality allows key interactions within the application, such as screen changes and user actions, to be recorded and interpreted, facilitating real-time behavior analysis.

Each event is sent with a timestamp, type, and specific detail, providing structured tracking and optimizing the user experience with precise and actionable data.

 SDKController.getAnalyticsEvents { time, componentName, eventType, info ->
            Log.i { "EVENTS", "*** $time - ${componentName.name} -" +
                " ${eventType.name} -  ${info ?: ""} " }
        }