"/home/yossef/notes/git/projects/maplibra/modules/Android Bridge.md"

path: maplibra/modules/Android Bridge.md

- **fileName**: Android Bridge
- **Created on**: 2026-06-16 00:48:42

Android Bridge

Purpose: Enables the web app to communicate with an Android WebView host.

Related: ../Home.md, ../Architecture.md, ./UI Components.md, ./Bootstrap System.md

What It Does

The Android bridge provides bidirectional communication between the web app and a native Android app embedding it in a WebView. It is used for floor state synchronization, native control rendering, and error reporting.

Bridge Detection

src/app/android-bridge.js detects the bridge via window.AndroidBridge:

• hasAndroidBridge — true if window.AndroidBridge exists
• shouldUseNativeControls() — true if bridge exists OR host is appassets.androidplatform.net

Floor State Sync

When floors change or the current floor changes:

• onFloorsChanged(JSON.stringify(floorOptions)) — sends all floor IDs and labels
• onFloorChanged(floorId, floorLabel) — sends current floor

Map Ready Signals

• onMapReady() — called when map finishes loading
• onMapMetadata(JSON.stringify({ manifestId, mapTitle, center, boundsFingerprint })) — sends map metadata
• onUploadReady() — called when page loads in upload mode (prevents native timeout error)
• onRouteFailed(message) — called when route calculation fails
• onMapError(message) — called when IndexedDB cache fails
• clearMapStorage() — called when clearing cached maps

Native Controls

When shouldUseNativeControls() is true:

• document.documentElement gets .native-controls class
• Floor controls render as a native-style dropdown menu instead of a <select>
• The top bar and other UI elements may be hidden or simplified

Important Files

• src/app/android-bridge.js — Bridge utilities and floor sync
• script.js — Bridge calls throughout startup and lifecycle

How It Connects

• bootstrapShell sets up viewport sizing specifically for mobile browsers

• UIManager calls notifyAndroidFloorState() on every floor change

• script.js reports map metadata and route failures to Android

• Settings menu "Clear cached maps" also calls AndroidBridge.clearMapStorage()

• The bridge is critical for the production mobile app experience

  continue:[[]]
  before:[[]]