Novarum Reader SDK iOS Integration

1.1. Overview

The Novarum SDK for iOS enables iOS applications to capture and analyze lateral flow tests using the device’s camera.
It handles camera setup, test image capture, and analysis result generation, allowing you to focus on the interpretation and presentation of the test outcomes.

This guide describes how to integrate the SDK into an iOS project using CocoaPods, configure required permissions, and use the core reader view in a SwiftUI application.

1.2. Platform Configuration

1.2.1. Minimum Deployment Target

The SDK supports both UIKit and SwiftUI-based applications running on iOS 14.2 or later.

1.2.2. Access to the Private Pod Repository

The Novarum SDK is distributed through a private CocoaPods repository hosted on Bitbucket.
To install the SDK, you must configure SSH authentication for the provided Novarum Bitbucket account.

1.2.2.1. Requirements

• Access to the NovarumDX Bitbucket account (credentials provided separately).

• Git LFS installed (required, as the SDK uses Git LFS to store binary artifacts).

• Access to CocoaPods (gem install cocoapods).

1.2.2.2. Steps

1. Set up SSH credentials for Bitbucket following Bitbucket’s SSH key setup guide.

2. Confirm connectivity:

   ssh -T git@bitbucket.org
   

   You should see a message confirming authentication.

3. Ensure Git LFS is installed:

   git lfs install
   

1.3. Pod Repository Configuration

Add the Novarum private repository to your app’s Podfile.

source 'https://cdn.cocoapods.org/'
source 'git@bitbucket.org:novarum-dx/ndxpodlibrary-client.git'

Then add the required dependencies:

pod 'OpenCV2', '4.12.0'
pod 'NdxImagingSwift', '3.0.0'

💡 Note:
The OpenCV version has been updated to 4.12.0 to match the Android SDK and ensure algorithmic consistency across platforms.

Run pod install to fetch and integrate the specified SDK version.

pod install

After installation, open the generated .xcworkspace file to continue development.

1.4. Permissions Configuration

The SDK requires camera access for capturing test images.
Add the following entry to your app’s Info.plist file:

<key>NSCameraUsageDescription</key>
<string>We will use this for scans</string>

This message appears in the iOS system prompt when the app requests permission to use the camera.

1.5. Using the SDK

The iOS SDK provides a ReaderView SwiftUI component that manages the full camera and analysis workflow.
It can be easily embedded into a SwiftUI view hierarchy.

1.5.1. Loading the Analyser Configuration

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

let json = "..." // contents of your analyser configuration JSON
let analyserConfiguration = PMFLoader.loadAnalyserConfiguration(json: json)

Note:
The parameter name has been updated from jsonString → json.

1.6. Using the Reader View (SwiftUI)

The ReaderViewWrapper is the primary SwiftUI component for embedding the Novarum reader experience within your app.
It manages the camera session, frame capture, and test analysis workflow.

1.6.1. Example Usage

@State private var progress: Double = 0.0
@State private var isAborted: Bool = false

ReaderViewWrapper(
    analyserConfiguration: analyserConfig,
    previewMode: .fill, // .fill or .fit
    onFrameCaptured: { callback in
        progress = Double(callback.progress)
    },
    onComplete: { model in
        // Handle completed analysis
    },
    onAbort: { model in
        // Handle abort event with collected data
    },
    isAborted: $isAborted
)

1.6.2. Parameter Overview

1.6.3. Callback Data Structures

The SDK provides strongly typed models for both the frame-level and full-analysis callbacks.
These structures define the data returned by the onFrameCaptured, onComplete, and onAbort closures.

1.6.3.1. FrameCapturedCallback

public struct FrameCapturedCallback {
    public let progress: Float
    public let resultPMF: ResultPMF
    public let orientation: [Double]
    public let lux: Float
}

Description:

Typically used in onFrameCaptured to update progress indicators or monitor capture conditions.

1.6.3.2. AnalysisModel

public struct AnalysisModel: Encodable {
    public let testConfig: TestConfiguration
    public let testStrips: [TestStrip]
    public let pmfStory: [FrameData]
}

Description:

Returned in the onComplete and onAbort callbacks, allowing your app to inspect or serialise the full analysis results.

1.6.4. Example Usage

onFrameCaptured: { callback in
    print("Progress: \(callback.progress * 100)% | Lux: \(callback.lux)")
}

onComplete: { model in
    print("Test strips detected: \(model.testStrips.count)")
    print("First C-line score: \(model.testStrips.first?.cLine?.score ?? 0)")
}

1.6.5. Related Data Types

The following supporting models are included within the AnalysisModel and FrameCapturedCallback objects.

For detailed property definitions, see the generated documentation in your Swift IDE (⌘ + click on type names).

1.6.6. Behaviour Notes

• When isAborted is toggled to true, the reader immediately halts scanning, performs cleanup, and invokes onAbort.

• When previewMode is set to .fit, the entire camera preview will remain visible without cropping — suitable for UI layouts where the full frame must be shown.
  .fillremains the default and ensures edge-to-edge display for most use cases.

💡 Tip: Combine isAborted with your app’s state management to implement user-triggered aborts or automatic cancellation (e.g., timeout scenarios).

1.6.7. Optional: SVG Overlay Visualisation

If your analyser configuration supports SVG overlay visualisation, the SDK will render overlays using high-resolution, scalable SVGs instead of the default dotMatrix mode.

• Default mode: dotMatrix

• To enable: Request an updated configuration file from your Novarum representative.

No code changes are required — the visualisation mode is determined by the configuration JSON.

1.7. Troubleshooting

1.8. Version Compatibility Summary

1.9. Support

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