IFU011(02) Reader SDK React Native Integration Guide

1. Overview

This guide explains how to integrate the Novarum Reader SDK for React Native into customer applications. The SDK supports camera capture, analysis, PMF fitting, strip status reporting, and result callback handling.

Version-specific changes, issue lists, and upgrade deltas should be kept in the relevant release notes rather than repeated here. For the v4.0.1 release-specific notes, including the changes from v3.0.2, see v4.0.1 Expo React Native.

2. Project Setup

2.1. Minimum Requirements

2.2. Registry Authentication

2.2.1. Installation

Access to the NovarumDX private npm registry is provided via AWS CodeArtifact. Before adding the dependency, install and configure the AWS CLI using the credentials provided by Novarum.

brew install awscli

2.2.2. Profile Configuration

aws configure --profile ndxcodeartifact

For non-interactive environments, configure credentials directly in the build environment:

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

2.3. NovarumDX NPM Registry Configuration

Configure npm to access the NovarumDX CodeArtifact registry.

The authentication token is scoped to the configured registry and expires periodically, so regenerate it when package installation fails due to registry authentication.

aws codeartifact login --tool npm --domain novarumdx --domain-owner 945969778369 --repository novarum.client.npm --profile ndxcodeartifact --namespace novarumdx

2.3.1. Module Installation

The npm module is self-contained for published-package consumers and includes the required native Android AAR and iOS XCFramework dependencies.

npm install @novarumdx/ndx-imaging-expo@4.0.1

Or:

yarn add @novarumdx/ndx-imaging-expo@4.0.1

Alternatively, edit the application package.json dependencies section:

{
  "dependencies": {
    "@novarumdx/ndx-imaging-expo": "4.0.1"
  }
}

2.4. Expo Configuration

Configure the minimum deployment targets in Expo app.json using the expo-build-properties plugin.

{
  "plugins": [
    [
      "expo-build-properties",
      {
        "ios": {
          "deploymentTarget": "16.4"
        },
        "android": {
          "minSdkVersion": 26,
          "compileSdkVersion": 36
        }
      }
    ]
  ]
}

2.5. Platform Configuration

The SDK requires access to the camera. Configure the camera permissions message in Expo using the included @novarumdx/ndx-imaging-expo config plugin.

[
  "@novarumdx/ndx-imaging-expo",
  {
    "cameraPermission": "Allow this app to access your camera to scan tests."
  }
]

2.5.1. Camera Permissions Request Example

import React from "react";
import { View, Text, Button } from "react-native";
import { useCameraPermissions } from "@novarumdx/ndx-imaging-expo";

function AppContent() {
  return <Text>Camera is ready. Your app goes here.</Text>;
}

export default function App() {
  const [permission, requestPermission] = useCameraPermissions();

  if (!permission) {
    return (
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center" }}>
        <Text>Loading...</Text>
      </View>
    );
  }

  if (!permission.granted) {
    return (
      <View style={{ flex: 1, alignItems: "center", justifyContent: "center", padding: 16 }}>
        <Text style={{ textAlign: "center", marginBottom: 16 }}>
          We need camera access to continue.
        </Text>
        <Button title="Grant Camera Permission" onPress={requestPermission} />
      </View>
    );
  }

  return <AppContent />;
}

3. Using the Reader View

The Novarum Analyzer Preview is the primary camera component used to display the live feed and perform test analysis.

3.1. Loading the Analyser Configuration

Load the analyser configuration JSON file provided by Novarum. For v4.x, confirm the file uses the current reader JSON format with the {estimators: [ wrapper.

import testConfigJson from './assets/test-config.json';

const testInfoJson = JSON.stringify(testConfigJson);

3.2. Displaying the Reader View

import React, { useRef } from 'react';
import { Button, StyleSheet, View } from 'react-native';
import {
  NdxImagingExpoView,
  type CompleteEvent,
  type AbortEvent,
  type FrameCapturedEvent,
} from '@novarumdx/ndx-imaging-expo';
import testConfigJson from './assets/test-config.json';

export function ScannerPage({ navigation }) {
  const cameraRef = useRef<any>(null);
  const testInfoJson = JSON.stringify(testConfigJson);

  return (
    <View style={styles.container}>
      <NdxImagingExpoView
        ref={cameraRef}
        style={styles.camera}
        testInfoJson={testInfoJson}
        previewMode="Fit"
        onFrameCaptured={({ nativeEvent }: { nativeEvent: FrameCapturedEvent }) => {
          const { frame } = nativeEvent;
          console.log('Frame progress:', frame.progress);
          console.log('PMF result:', frame.resultPMF);
          console.log('Strip statuses:', frame.stripStatuses);
          console.log('Lux:', frame.lux);
          console.log('Orientation:', frame.orientation);
        }}
        onComplete={({ nativeEvent }: { nativeEvent: CompleteEvent }) => {
          const { resultModel } = nativeEvent;
          console.log('Scan complete!', resultModel);
          navigation.navigate('ResultDetail', resultModel);
        }}
        onAbort={({ nativeEvent }: { nativeEvent: AbortEvent }) => {
          const { resultModel } = nativeEvent;
          console.log('Scan aborted', resultModel);
          navigation.navigate('ResultDetail', resultModel);
        }}
      />
      <Button title="Cancel" onPress={() => cameraRef.current?.abort()} />
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: '#000',
  },
  camera: {
    flex: 1,
  },
});

3.3. Parameter Overview

3.4. Callback Data Structures

export type FrameCapturedCallback = {
  /** Fractional progress of the capture or analysis (0.0 to 1.0). */
  progress: Float;
  /** Result from the Point Model Fitter (PMF) analysis. */
  resultPMF: keyof typeof ResultPMF;
  /** Statuses of detected strips in the frame. */
  stripStatuses: (keyof typeof StripStatus)[];
  /** Device or image orientation as [roll, pitch, yaw] (Euler angles). */
  orientation: Double[];
  /** Ambient light level in lux. */
  lux: Float;
};

3.4.1. ResultModel

3.4.2. ResultModel

3.5. Related Data Types

For full type definitions, refer to the TypeScript source declarations in the @novarumdx/ndx-imaging-expo package.

3.6. Behaviour Notes

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

• The v4.0.1 layout fixes should be regression-tested in full-screen, flex, embedded, and partial-screen layouts on both iOS and Android.

• Screen keep-awake: while the reader is visible, the SDK keeps the screen active during capture. Verify on physical release builds that normal dimming and auto-lock behaviour resumes after leaving the reader.

• Backgrounding/foregrounding: when the app is backgrounded, the SDK releases the camera session. On foregrounding, the camera reinitialises automatically. Verify that the reader resumes correctly on physical devices after a background/foreground cycle.

• PMFInitialHScaleFactor is part of the test configuration passed to the module. Set it in testConfig.PMFInitialHScaleFactor; where the configuration also includes pointModel.initial_h_factor, keep both values aligned.

3.7. 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. Support & Troubleshooting

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

For streamlined support and rapid troubleshooting, users can access the Novarum service desk. This portal provides a direct channel for submitting integration queries, reporting issues, and tracking the status of requests.

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

5. Version Compatibility Summary

This guide intentionally avoids duplicating release-specific change logs. Use the release note for the SDK version being integrated to confirm exact package version, supported Expo and native build baselines, known issues, and upgrade actions.

• v4.0.1 Expo React Native release note

6. Document History