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
toanura-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
MediaPipe is not tied to your application ID, and does not require a separate license file for each variant of your application.
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:
- Update
kotlin_version
to '1.8.0' or newer - Add the Kotlin serialization Gradle plugin to your project's
build.gradle
:classpath "org.jetbrains.kotlin:kotlin-serialization:$kotlin_version"
- Add Kotlin serialization dependency to your application's
build.gradle
:implementation "org.jetbrains.kotlinx:kotlinx-serialization-json:1.1.0"
- Optional: If your application does not utilize
getDefaultProguardFile
in itsbuild.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.
You may safely stop using the workaround we provided for the duplicate protobuf classes issue if your application had encountered it when using Anura Core SDK 2.3.x and Google Firebase https://github.com/kamalh16/protobuf-javalite-firebase-wellknowntypes.
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.