Integration Guide

This section provides a technical overview of the freeMalware Detection module's execution flow. Understanding this operational lifecycle is a critical prerequisite for a successful integration, as it defines precisely when vulnerability scans occur, how state is managed, and how threat results are dispatched to the application.

---

The Detection Pipeline

Upon initialization, the detection engine executes a strict, automated pipeline before delivering any threat telemetry. The process is designed to minimize battery consumption and optimize startup performance through asynchronous batch operations.

---

• Handling Configuration Changes: On each launch, the engine checks whether the active detection configuration has changed since the last scan. If a change is detected, the internal cache of previously evaluated applications is purged, and all packages are re-evaluated from scratch against the updated definitions.

• Asynchronous Batch Evaluation: The scanning process is offloaded to a background thread. For each installed application, the engine first checks whether it was already recorded in the safe cache from a previous scan, and — if not — whether it is explicitly trusted. Applications that satisfy either condition are skipped without further evaluation. Only the remaining applications are passed to the on-device malware evaluator, which requires no network connectivity.

• Safe Cache & Trust Management: Only after the entire evaluation batch successfully completes are applications marked as benign recorded in a persistent internal cache. Explicitly trusted applications are bypassed at evaluation time but are not written to the cache, as they are re-identified on each launch. During subsequent launches (provided the configuration remains unchanged), cached applications are bypassed entirely, resulting in near-instantaneous initialization times. However, if the application is terminated before the background batch completes, the safe cache is not updated and the full scan will restart upon the next launch.

• Threat Callback Dispatch: The final threat callback is dispatched on the main thread only after all installed applications have been successfully evaluated.

---

Application Lifecycle Constraints

Because comprehensive background scanning is a resource-intensive operation, the detection engine limits its execution frequency.

Single Execution per Process

The freeMalware Detection callback is triggered only once per application process lifecycle, immediately following the initial scan.

The scan does NOT re-trigger when the application transitions between background and foreground states (e.g., when the user minimizes and later resumes the app).

Recommended Implementation Strategy

Since the engine will not continuously re-notify the application of an existing threat upon resuming, the host application architecture must handle threat state retention.

To prevent users from bypassing your security screen by backgrounding and resuming the application, your UI logic must maintain awareness of the threat:

1. Persist the Threat State: When the callback fires, save a flag (e.g., isMalwareDetected = true) in your application's session memory.

2. Enforce on Resume: Whenever the application returns to the foreground (e.g., via Android's onResume, Flutter's AppLifecycleState.resumed, or React Native's AppState.currentState), check this saved flag. If the flag is true, immediately re-display your blocking UI.

---

Threat Remediation Validation

Because the detection engine operates on a scanning schedule rather than real-time monitoring, it does not provide uninstallation hooks. If a user removes a malicious application, the SDK does not notify you directly; the threat will simply be omitted from the results of the next background scan.

To programmatically verify that the device environment is secure after a user claims to have remediated the threat, implement the following strategy:

• Dynamic OS Validation: Utilize standard operating system APIs (such as Android's PackageManager) to actively query if the offending package name is still present on the system.