SDK Initialization and Configuration

Every call to the SDK is made through the singleton object obtained with PassioSDK.instance call. The SDK is designed to be called from the main thread, and it will deliver results to the main thread. Its internal tasks will be run by Passio threads, so you don't need to manage the threading execution.

Two things are required for the SDK to work: a proper license key and the neural network files that the SDK uses to run the recognition process.

• The license key can be requsted at [e-mail]

• The files are shipped inside the PassioSDKSandbox project on the releases page of the Android-Passio-SDK-Distribution repository. Unzip the PassioSDKSandbox project and locate the files in the assets folder: /PassioSDKSandbox/app/src/main/assets. Files that the SDK needs have an extension .passiosecure and are encrypted

There are several ways to initialize the SDK depending on the location of the needed files:

1. Files are in the assets folder of your Android project

2. Let the SDK manage file download and update

3. Host the files on your own server, download the files, store them on the device's memory and point the SDK to the URIs of the needed files

For a first time integration the first approach is recommended

1. Files are located in the Assets folder

• If the assets folder is not already present in your Android project, create one in the module where the SDK dependencies are located under the main directory (e.g. app/src/main/assets)

• Transfer the .passiosecure files to the assets folder

• Create a PassioConfiguration object with the application context and the license key

• Call the configure method of the PassioSDK without changing the default PassioConfiguration object

val passioConfiguration = PassioConfiguration(
    this.applicationContext,
    "Your license key here"
)

PassioSDK.instance.configure(passioConfiguration) { passioStatus ->
    // Handle PassioStatus states
}

2. The SDK will manage the download and updates

By setting the sdkDownloadsModels field to true the SDK will do the initial download of the files. If the current files that are present on the device are older than the version of the SDK library, the SDK will download the newer version in the background, but still run the session with the older version of the files. Once the download is finished, the new files will be applied on the next session.

val passioConfiguration = PassioConfiguration(
    this.applicationContext,
    "Your license key here"
).apply {
    sdkDownloadsModels = true
}

PassioSDK.instance.configure(passioConfiguration) { passioStatus ->
    // Handle PassioStatus states
} 

To track the download process you can implement a PassioStatusListener (recommended to define after the PassioStatus mode returns IS_DOWNLOADING_MODELS)

3. Files are located in local device storage

This approach is recommended if you are responsible for the download of the files. In this case the SDK does not care where the files are hosted and how they are downloaded, just where they are stored after the download has completed. Use the PassioConfiguration object to modify the initialization process with local files and pass the URIs of the files to the localFiles field.

val passioConfiguration = PassioConfiguration(
    this.applicationContext,
    "Your license key here"
).apply {
    localFiles = /*List of files URIs*/
}

PassioSDK.instance.configure(passioConfiguration) { passioStatus ->
    // Handle PassioStatus states
} 

After the configuration process is successful, delete the files from local device storage. The SDK will copy them over to its internal folder.

Handle the configuration response

When you call the configure method of the Passio SDK with the PassioConfiguration object, you will need to define a callback to handle the result of the configuration process. This result is comprised in the PassioStatus object.

class PassioStatus {
    var mode: PassioMode
    var missingFiles: List<FileName>?
    var debugMessage: String?
    var activeModels: Int?
}

The mode of PassioStatus defines what the current status of the configuration process is. There are 5 different modes, and they all should be handled by the implementing side.

enum class PassioMode {
    NOT_READY,
    FAILED_TO_CONFIGURE,
    IS_BEING_CONFIGURED,
    IS_DOWNLOADING_MODELS,
    IS_READY_FOR_DETECTION
}

• NOT_READY -> The configuration process hasn't started yet.

• FAILED_TO_CONFIGURE -> The configuration process resulted in an error. Be sure to check the debugMessage of the PassioStatus object to get more insight into the nature of the error.

• IS_BEING_CONFIGURED -> The SDK is still in the configuration process. Normally, you shouldn't receive this mode as a callback to the configure method.

• IS_DOWNLOADING_MODELS -> The files required for the SDK to work are not present and are currently being downloaded.

• IS_READY_FOR_DETECTION -> The configuration process is over and all the SDKs functionalities are available.

The missingFiles variable contains a list of all the files missing for the SDK to work optimally. When this list is not null, this doesn't mean that the SDK is not operational. The SDK may be initialized with older files, but it will advocate the download of the newest files through this list.

The debugMessage usually gives more verbose and human-readable information about the configuration process. It will always give an error message if the mode is FAILED_TO_CONFIGURE.

The activeModels will give the version of the files installed and ran by the SDK if the configuration process ran successfully i.e. if the mode is IS_READY_FOR_DETECTION.

Best practices

1. The PassioStatus mode is NOT_READY -> check debugMessage for the error, usually the wrong license key has been supplied or the files are missing.

2. The PassioStatus mode is IS_DOWNLOADING_MODELS -> register a PassioStatusListener through the PassioSDK.instance.setPassioStatusListener() method as it will enable tracking of the download progress.

3. The PassioStatus mode is IS_READY_FOR_DETECTION -> still check the missingFiles because the SDK might be running with an older version of the files and newer need to be downloaded.

If at any point you need help from the Passio team, please reach out to us at [e-mail]