Anura Core SDK Android 2.4.0 Migration Guide

Anura Core SDK Android 2.4.0 is a major update that includes the following improvements and features:

• Significant camera and face tracker performance improvements
• New measurement UI that utilizes the device's screen as a light source for more accurate and reliable measurements
• Replaced the existing Visage FaceTracker with MediaPipe face tracker for improved performance and simplified integration
• Improved WebSocket handling in poor network conditions
• Simplified measurement results parsing
• DeepAffex token security enhancements

Upgrading to Anura Core Android 2.4.0

A few steps are required to upgrade your existing app from Anura Core 2.3.x to 2.4.0.

Updating SDK Binaries

Replace the existing Anura Core SDK AAR binary, and update your application's build.gradle file:

• anura-core-sdk-2.3.0.aar to anura-core-sdk-2.4.0-XXXX.aar

Remove the existing anura-cream-ui-1.1.0.aar AAR binary. It's no longer needed and its functionality has been merged into anura-core-sdk-2.4.0-XXXX.aar

Adopting the new UI

Anura Core SDK 2.4.0 features a new measurement UI that utilizes the device's screen as a light source for more accurate and reliable measurements.

Adopting the new measurement UI is as simple as passing a new instance of MeasurementUIConfiguration to your application's MeasurementView instance:

measurementView.setMeasurementUIConfig(MeasurementUIConfiguration())

If you would like to continue to use the exiting UI, you can use MeasurementUIConfiguration.anuraDefaultLegacyUIConfiguration instead:

measurementView.setMeasurementUIConfig(MeasurementUIConfiguration.anuraDefaultLegacyUIConfiguration)

The Measurement UI is also now very easy to configure, here are all of the configuration options;

// create a custom UI configuration and set the desired values
val customMeasurementUIConfig = MeasurementUIConfiguration().apply {
    measurementOutlineStyle = MeasurementUIConfiguration.MeasurementOutlineStyle.OVAL
    showHistograms = true
    overlayBackgroundColor = Color.WHITE
    measurementOutlineActiveColor = Color.BLACK
    measurementOutlineInactiveColor = Color.WHITE
    histogramActiveColor = Color.YELLOW
    histogramInactiveColor = Color.GREEN
    statusMessagesTextColor = Color.CYAN
    timerTextColor = Color.BLUE
}
// set the measurement view's configuration
measurementView.setMeasurementUIConfig(customMeasurementUIConfig)

The updated Sample App also includes code to automatically maximize the brightness of the screen when a face is detected and during the measurement. Your existing application should be updated to include this functionality to best utilize the device's screen brightness as a light source.

Face Position & Distance Constraint

As part of the new measurement UI, Anura Core SDK 2.4.0 requires users to come closer to the device's camera. This is done to allow the light from the device's screen to illuminate the user's face and get more reliable and accurate measurements. You should update your application's DfxPipeConfiguration instance to set CHECK_FACE_DISTANCE to true as shown below:

private fun getDfxPipeConfiguration(): DfxPipeConfiguration {
    val dfxPipeConfiguration =
    DfxPipeConfiguration(applicationContext, null)
    // set face_distance constraint on
    dfxPipeConfiguration.setRuntimeParameter(
        DfxPipeConfiguration.RuntimeKey.CHECK_FACE_DISTANCE,
        true
    )
    return dfxPipeConfiguration
}

The updated Sample App also includes code to show the users instructions to come closer before the measurement starts. Please refer to the Sample App's AnuraExampleMeasurementActivity code, specifically under onMeasurementConstraint() callback method.

MeasurementPipeline Updates

The updated MeasurementPipeline interface and default implementation utilize a new MeasurementState class to manage the internal state. Your application can observe the state as demonstrated in the updated Sample App:

override fun onMeasurementStateLive(measurementState: LiveData<MeasurementState>?) {
    measurementState?.observe(this) { newState: MeasurementState ->
        handleMeasurementViewState(state = newState)
    }
}

Refer to the Sample App's example implementation of handleMeasurementViewState() in AnuraExampleMeasurementActivity on how to handle state changes.

The updated MeasurementPipeline also includes a new method for determining if a measurement should be cancelled early:

measurementPipeline.shouldCancelMeasurement(results.snr, resultIndex)

In previous versions of the Sample App, the measurement early cancellation logic was in the example code. If your application was using that code, you should replace that code with a call to this new method.

MediaPipe Face Tracker

Anura Core Android 2.4.0 includes support for MediaPipe face tracker which provides improved performance, a smaller binary size, and simplifies integration with your application.

To start using MediaPipe, include it as a dependency in your application's build.gradle:

mediaPipeVersion = "0.10.2"

implementation ("com.google.mediapipe:solution-core:$mediaPipeVersion")
implementation("com.google.mediapipe:facemesh:$mediaPipeVersion")

You may also remove Visage FaceTracker and its dependencies and assets:

• anura-visage-2.3.0.aar
• visage assets folder
• Any .vlc license file

Visage FaceTrack support

If you would like to continue using Visage FaceTrack, please use the updated anura-visage-2.4.0.XXXX.aar. The updated binaries and Visage assets folder are included under this repo's /visage directory.

New MeasurementResults Class

The new MeasurementResults class replaces the existing AnalyzerResult and AnalyzerResult2 classes for parsing real-time results from DeepAffex Cloud. MeasurementResults has a simple allResults interface to get all the available results and notes for each point in key/value pairs. MeasurementResults can be serialized into JSON or parceled for passing to another Android activity.

AnalyzerResult and AnalyzerResult2 classes are still available in Anura Core Android 2.4.0, but these are deprecated and will be removed in the future.

MeasurementResults requires kotlinx.serialization to work. If your application does not use kotlinx.serialization, follow these steps:

1. Update kotlin_version to '1.8.0' or newer
2. Add the Kotlin serialization Gradle plugin to your project's build.gradle:

   classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
   

3. Add Kotlin serialization dependency to your application's build.gradle:

   implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.1.0"
   

4. Optional: If your application does not utilize getDefaultProguardFile in its build.gradle file, you need to add the proguard rules to your proguard-rules.pro file not to break kotlin-serialization when minifying and obfuscating the code in release mode.

Removing Protobufs

Protobufs are no longer used in Anura Core Android 2.4.0, and can be removed from your application's dependencies.

Improved DeepAffex Cloud API Client

Anura Core Android 2.4.0 includes an improved DeepAffex Cloud API client that can better handle WebSocket connections in poor network conditions.

Your application will automatically get these improvements by simply using the latest Anura Core SDK Android 2.4.0 binaries and implementing the TokenStore. Please refer to the included SampleTokenStore for an example.

An important security update to the DeepAffex Cloud API was released on November 28, 2023, which expires tokens after a fixed duration. This will impact your user's experience if you choose to keep using the older Anura Core SDKs. Upgrading to the latest Anura Core SDKs ensures seamless adaptation to these API changes.

Miscellaneous Changes

ProGuard Rules

Anura Core SDK 2.4.0 includes consumer ProGuard rules, so your application will no longer need to maintain its own ProGuard rules to support Anura Core SDK if used in conjunction with getDefaultProguardFile in build.gradle:

proguardFiles getDefaultProguardFile('proguard-android-optimize.txt')

You may safely remove existing ProGuard rules from your application that were added to support previous versions of Anura Core SDK.

RestClient

The token has been renamed to actionId.

The endpoint getLicenseStatus has been renamed to verifyToken to better match the api naming.

The constant RestClient.ACTION_EXPIRE_LICENSE has changed to RestClient.ACTION_VERIFY_TOKEN

AnuraError

AnuraError Class has been split into either Network related errors or Core related errors.

For example, AnuraError.LICENSE_EXPIRED is now AnuraError.Network.LICENSE_EXPIRED

Network errors

RestClient's onError callback now provides AnuraError.NetworkErrorInfo data class rather than just a message and token number.

The class will now provide the actionId, errorCode, errorMessage and the responseCode.

Measurement Pipeline Listener

Added callback method onMeasurementFaceDetected that provides a boolean isFaceDetected.

Added two other callback methods for debugging purposes onCameraFrameRate and onFaceTrackerFrameRate, which provide the frames per second (fps) measured.