IFU009(01) Reader SDK Android Integration Guide

1. Overview

The Novarum SDK enables Android applications to capture and analyze lateral flow tests using the device’s camera.
It handles camera setup, image analysis, and result delivery, allowing developers to focus on interpreting and presenting test results in their own UI.

This guide describes how to integrate the SDK into an Android project using Gradle and AWS CodeArtifact.

2. Project Setup

2.1. Minimum Requirements

2.2. AWS CLI Configuration

Access to the Novarum SDK Maven repository is provided via AWS CodeArtifact.
Before adding the dependency, you must install and configure the AWS CLI.

2.2.1. Installation

Refer to AWS Command Line Interface for installation details.
On macOS, you can install via Homebrew :

brew install awscli

2.2.2. Profile Configuration

You’ll need the AWS credentials provided by Novarum.

Interactive setup:

aws configure --profile ndxcodeartifact

You’ll be prompted for:

• Access Key ID

• Secret Access Key

• AWS Region (e.g., eu-west-2)

For non-interactive environments (CI, build agents), configure directly:

aws configure set aws_access_key_id "${ECR_KEY}"
aws configure set aws_secret_access_key "${ECR_SECRET}"
aws configure set region "${AWS_REGION}"

2.3. Maven Repository Configuration

Add the Novarum Maven repository to your root build.gradle or settings.gradle file.

This configuration retrieves an authorization token for each build from AWS CodeArtifact.

def codeartifactToken = "aws codeartifact get-authorization-token --domain novarumdx --domain-owner 945969778369 --query authorizationToken --output text --profile ndxcodeartifact".execute().text.trim()

allprojects {
    repositories {
        maven {
            credentials {
                username = 'aws'
                password = codeartifactToken
            }
            url 'https://novarumdx-945969778369.d.codeartifact.eu-west-2.amazonaws.com/maven/novarum.client.maven/'
        }
        google()
        mavenCentral()
    }
}

2.4. Gradle Configuration

Ensure your module build.gradle uses the following settings:

android {
    namespace "com.example.app"
    compileSdk = 35

    defaultConfig {
        minSdk = 26
        targetSdk = 35
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_17
        targetCompatibility JavaVersion.VERSION_17
    }

    kotlinOptions {
        jvmTarget = "17"
    }
}

dependencies {
    implementation "org.novarumdx:camerax:<version>"
}

2.5. Android Manifest Configuration

The SDK requires access to the camera.
Add the following entries to your app’s AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA"/>
<uses-feature android:name="android.hardware.camera" android:required="true" />

If your app targets Android 13+ and uses runtime permissions, request android.permission.CAMERA before starting a scan.

3. Using the Reader View

The Novarum Analyzer Preview is the primary camera component used to display the live feed and perform the test analysis.
It can be embedded in either a traditional XML layout or a Jetpack Compose UI, depending on your project setup.

3.1. Loading the Analyser Configuration

Load the analyser configuration JSON file you were provided by Novarum:

val configJson = /* your analyser configuration JSON */
val analyserConfiguration = PMFLoader.loadAnalyserConfiguration(json = configJson)

3.2. XML-Based Integration

For standard View-based layouts, include the NovarumAnalyzerPreview directly in your XML layout file:

<org.novarumdx.camerax.NovarumAnalyzerPreview
    android:id="@+id/previewView"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Then configure it in your Activity or Fragment:

binding.previewView.analyzerConfig = analyserConfiguration
binding.previewView.previewMode = PreviewMode.Fill

binding.previewView.onFrameCaptured = { callback ->
    // Track scan progress, brightness, orientation, etc.
    val progress = callback.progress
}

binding.previewView.onComplete = { result ->
    // Handle analysis completion
}

val result = binding.previewView.abort() // Aborts the scan if required

3.3. Compose Integration

The SDK is compatible with Compose UI, the NovarumAnalyzerPreview can be directly wrapped by a composable.

@Composable
fun ReaderView(
    analyserConfiguration: AnalyserConfiguration,
    onComplete: (AnalysisModel) -> Unit = {},
    onAbort: (AnalysisModel?) -> Unit = {},
    previewMode: PreviewMode = PreviewMode.Fill,
) {
    var progress by remember { mutableFloatStateOf(0f) }
    var orientation by remember { mutableStateOf(listOf<Double>()) }
    var lux by remember { mutableFloatStateOf(0f) }
    var isFinished by remember { mutableStateOf(false) }
    val context = LocalContext.current
    val preview =
        remember {
            NovarumAnalyzerPreview(context).apply {
                // Configure the view right after creation.
                this.analyzerConfig = analyserConfiguration
                this.onFrameCaptured = { callback ->
                    progress = callback.progress
                    orientation = callback.orientation
                    lux = callback.lux
                }
                this.onComplete = { result ->
                    isFinished = true
                    onComplete(result)
                }
                this.previewMode = previewMode
            }
        }

    Box(modifier = Modifier.fillMaxSize()) {
        AnimatedVisibility(
            visible = !isFinished,
            exit = fadeOut(animationSpec = tween(durationMillis = 300)), // 300ms fade-out
        ) {
            AndroidView(
                factory = { preview },
                modifier =
                    Modifier
                        .fillMaxWidth(),
            )
        }
    }
    BackHandler {
        onAbort(preview.abort())
    }
}

3.4. Parameter Overview

3.5. Callback Data Structures

The SDK exposes several structured models representing frame-level and result-level data.

3.5.1. FrameCapturedCallback

data class FrameCapturedCallback(
    val progress: Float,
    val resultPMF: ResultPMF,
    val stripStatuses: List<StripStatus>,
    val orientation: List<Double>,
    val lux: Float,
)

3.5.2. ResultModel

data class AnalysisModel(
    val testConfiguration: TestConfiguration,
    val testStrips: List<TestStrip>,
    val pmfStory: List<FrameData>,
)

3.6. Related Data Types

3.7. Behaviour Notes

• previewMode determines how the live camera preview scales to your layout. Fill (default) maximises coverage, while Fit ensures full frame visibility.

• The abort() method immediately stops scanning and triggers onAbort, returning partial data.

• Both XML and Compose integrations share the same underlying NovarumAnalyzerPreview logic.

3.8. Optional: SVG Overlay Visualisation

The SDK supports an optional SVG-based overlay rendering mode for higher-quality graphics and scalable test result visuals.

• Default visualisation mode: dotMatrix

• To enable SVG overlays, request an updated Analyser Configuration File from Novarum support.

• No code changes are required — the overlay mode is controlled via configuration.

4. Version Compatibility Summary

4.1. Native Code Considerations

If your app or modules build native (JNI/C++) components:

• Update to NDK r29.0.14033849 rc4

• Update CMake to 3.22.1

• Rebuild your project with:

  ./gradlew clean assembleRelease
  

This ensures compatibility with the SDK’s OpenCV 4.12.0 dependency.

5. Support & Troubleshooting

For access credentials, configuration files, or integration assistance, please contact your Novarum support representative or technical account manager.

For streamlined support and rapid troubleshooting, users can access the https://novarum.atlassian.net/servicedesk/customer/portal/15 . This portal provides a direct channel for submitting integration queries, reporting issues, and tracking the status of your requests. In addition, the service desk is equipped with an intelligent agent capable of answering common technical questions and guiding you through standard troubleshooting steps.

We recommend using this resource for the fastest resolution of SDK-related issues or to obtain up-to-date technical guidance.

6. Document History