Overview

This document gives a high-level overview of the main integration points in the app — how the WebView, native Android layer, BLE stack, and backend APIs work together.

The goal is to explain what talks to what, and which contracts (callbacks, handlers, endpoints) are involved, without going into low-level implementation details.

High-Level Picture

At a high level, there are three main layers:

1. WebView (Frontend JS)

   • Renders the UI.
   • Uses bridgeWebView to talk to the native Android layer.

2. Native Android Layer

   • Implemented in BaseWebViewActivity and related classes.
   • Exposes a set of bridge handlers (e.g. startBleScan, connBleByMacAddress, initBleData, etc.).
   • Integrates with the Android BLE stack and with network/API clients.

3. Backend / External Services

   • HTTP/REST or GraphQL endpoints the app calls for configuration, device metadata, user data, etc.
   • Optional third-party services (logging, analytics, authentication), if configured.

Each of these layers has a clear contract so they can evolve independently.

1. WebView ↔ Native Bridge Integration

Purpose: Allow JavaScript running inside the WebView to call native functions and receive callbacks.

Key concepts:

• bridgeWebView.callHandler(name, payload, callback)

  • JS → Native call (e.g. startBleScan, connBleByMacAddress, initBleData).
  • payload is usually a stringified JSON object.
  • callback receives a JSON string response from native.

• bridgeWebView.registerHandler(name, callback)

  • Native → JS calls (events).
  • JS registers handlers like:
    • findDeviceCallback (device discovered during scan)
    • connectSuccess (device connected successfully)
    • connectFail (connection failed or timed out)
    • onCompleteCallback (BLE data initialization finished)
    • Any additional app-specific events.

Responsibilities:

1. WebView never talks directly to BLE or the OS.
2. WebView only calls well-defined bridge methods and listens to registered callbacks.
3. The bridge acts as a thin API layer between JS and Android.

You can think of this as a mini “internal API” exposed to the frontend.

2. Native Layer ↔ BLE Stack Integration

Purpose: Encapsulate all BLE operations behind a stable set of Java ↔ JS bridge methods.

Typical responsibilities include: - Checking phone BLE status - getPhoneBleStatus() is exposed to JS and uses Android APIs to check:

    - Bluetooth hardware support
    - Whether Bluetooth is enabled
    - Any required permissions

• Scanning for devices

  • startBleScan() / stopBleScan() map to Android’s BLE scan APIs.
  • As devices are found, native serializes them to JSON and invokes findDeviceCallback in JS.

• Connecting to devices

  • connBleByMacAddress(macAddress) wraps the connection logic.
  • On success/failure/timeout it triggers connectSuccess or connectFail on the JS side.

• Data initialization

  • initBleData() encapsulates:
    • Service and characteristic discovery
    • Optional initial reads
    • Preparing internal mappings needed by later read/write/notify operations.

• When initialization is done, it triggers onCompleteCallback in JS.

This integration keeps all BLE complexity in the native code, while exposing a simple high-level API to the WebView.

3. WebView / Native ↔ Backend API Integration

Purpose: Synchronize device state and user actions with the backend.

Where this lives depends on your architecture:

• WebView → Backend

  • JS calls HTTP/GraphQL APIs directly from the WebView (for device metadata, user accounts, dashboards, etc.).

• Native → Backend

  • Native Android code calls APIs when BLE operations need to be associated with server-side state (e.g. registering a device, sending telemetry, or syncing configuration).

Typical integration points:

• Authentication

  • Passing tokens/headers to backend endpoints.
  • Handling expired tokens and re-auth flows.

• Device registration & metadata

  • Mapping discovered MAC addresses or serial numbers to backend device records.
  • Enriching BLE data with server-side metadata (names, models, owners, etc.).

• Telemetry / logging

  • Optionally sending BLE readings, errors, and session logs to the backend for monitoring and analytics.

These APIs are usually documented separately in the API and Endpoints section (paths, request/response shapes, versioning).

4. Versioning & Compatibility Between Integrations

Because there are multiple layers, versioning matters:

• Bridge API version

  • The set of handlers (e.g. startBleScan, connBleByMacAddress) forms a contract between WebView and native.
  • Any breaking change should bump a bridge version and be coordinated between app versions.

• BLE Protocol version

  • The device GATT structure (services, characteristics, payload formats) should be versioned, especially if firmware evolves over time.

The integrations documentation should clearly state which versions are expected to work together

5. Error Handling & Retries Across Integrations

Integrations are often where most failures happen, so we treat error handling as a first-class concern:

• WebView ↔ Native

  • All callHandler responses should include a success flag and an error message or code.
  • JS should display user-friendly errors and offer retries.

• Native ↔ BLE

  • Handle common BLE issues: timeouts, disconnections, permissions, unsupported features.
  • Map low-level error codes into simple outcomes (connectFail, timeout, etc.) consumed by JS.

• App ↔ Backend

  • Network failures and HTTP errors should surface as structured error responses, not crashes.
  • Implement safe retry strategies where appropriate (idempotent operations).

Where to Go Next

This Integrations Overview is meant as an entry point. Detailed behavior for each integration is documented in dedicated pages:

• BLE Workflow – step-by-step BLE sequence (status → scan → connect → init → read/write/notify).
• WebView Initialization – how the WebView is set up, how the bridge is attached, and which handlers are registered at startup.
• API and Endpoints – detailed reference for backend routes, payloads, auth, and versioning.