Skip to content

Latest commit

 

History

History
77 lines (43 loc) · 13.1 KB

android.md

File metadata and controls

77 lines (43 loc) · 13.1 KB

Android builds and installation

The application is an Expo native app. MapLibre requires a compiled native build; Expo Go cannot run it. Android uses MapLibre's default platform location engine, with foreground approximate or precise permission. Search and manual map browsing work without location access. Version 0.1.8 introduced an explicit Android navigation session using precise platform positioning, a location foreground service and an installed offline Italian voice. Complete physical GPS/voice/service acceptance remains outstanding; read navigation implementation and acceptance before describing screen-off guidance as tested.

Local prerequisites

Use Node 22, JDK 17, Android SDK platform 36, build-tools 36.0.0, NDK 27.1.12297006, and CMake 3.22.1. scripts/toolchain-env.sh selects the existing task-local tools in ~/.local/share/avoid-maps/toolchain; otherwise set JAVA_HOME and ANDROID_HOME to your own installation. Dependencies are pinned by bun.lock; use the Bun version declared in package.json.

Source scripts/toolchain-env.sh if using the prepared local Node/Android tools, then run bun install --frozen-lockfile. Build commands are in package.json.

The minimum supported Android API is 25 (Android 7.1) for the navigation build. The navigation dependency boundary records the Kotlin/R8/desugaring pins.

The release build generates android/ through Expo prebuild and invokes Gradle locally. It bundles JavaScript and assets into the APK, so installation requires neither Metro nor an Expo account. Generated native directories and build outputs are ignored by Git. Native customizations belong in config plugins; the tracked local Expo navigation module owns its Android source, service manifest and third-party notice assets.

The build script supplies a temporary Gradle init script that appends Clang -ffile-prefix-map flags for the checkout, Gradle cache and local home prefixes. These paths come from the current build environment and map to relative paths in C/C++ source strings. This removes local compiler-header paths without excluding native sources or packaging metadata. The init script is deleted on exit. Scan the resulting APK for local paths as part of release inspection; JavaScript and prebuilt dependencies require their own content checks.

Expo development

Use Expo’s local development workflow with expo-dev-client. Expo Go cannot load this app’s MapLibre and local Kotlin modules. The application variant gives avoid maps dev its own package so it can coexist with the release.

After selecting the toolchain above, connect an Android device through authorized USB or wireless ADB:

bun run prebuild:android:dev
bun run android --device

These run Expo’s clean prebuild and expo run:android; Expo builds, installs, and starts Metro. For subsequent JavaScript/UI work, use bun start and Fast Refresh. Press j in the Expo terminal for React Native DevTools and m for the developer menu. LAN Metro connectivity is separate from ADB authorization.

Run clean prebuild again after native dependency/configuration changes or after building the production variant; rebuild with bun run android after Kotlin changes. Generated native files remain disposable. The explicit development scheme in bun start selects the installed Dev app even when the generated native directory describes production. On devices without Google services, open its development link or enter the Metro address instead of using the launcher’s Google-powered QR scanner.

Use Android Studio only when inspecting Kotlin/provider callbacks; DevTools handles JavaScript and React. Keep raw coordinates, requests and device logs private. Position reception, Fast Refresh on a physical device, and release startup with Metro stopped each require device verification.

Production prebuild excludes the development launcher through Expo's Android autolinking settings. The launcher carries Google barcode-scanner dependencies even in its release variant; changing the application ID alone does not isolate them. Development prebuild keeps the launcher and menu. The empty Android expo-dev-client wrapper is excluded in both variants: its test-only project references otherwise require the launcher even in production. SDK 54 serializes multiple Gradle exclusions as one argument, so the shared wrapper exclusion belongs in package autolinking configuration and the production-only launcher exclusion in settings. Inspect the production runtime graph and merged manifest after changing Expo development tooling.

Signing and updates

The release signing key lives outside the checkout at ~/.local/share/avoid-maps/signing/release.jks; its local password configuration is release.properties in the same directory. Back up both files privately. Keeping this key allows future APKs to update the app while retaining favourites. Losing it requires uninstalling the app before installing a newly signed build, which removes app data.

Set AVOID_MAPS_SIGNING_PROPERTIES to use a different properties file with storeFile, storePassword, keyAlias, and keyPassword. The build fails when this configuration is absent. Signing material must remain outside Git and APK artifacts.

bun run build:android produces artifacts/avoid-maps.apk and its SHA-256 file. The script verifies APK signatures and 16 KB zip alignment. The default is arm64; AVOID_MAPS_ARCH=x86_64 selects an emulator build.

Install by copying the APK to the Android device and opening it in Files, or use adb install -r artifacts/avoid-maps.apk with USB debugging authorized. Grant the installer permission to install unknown apps when Android requests it. App id: quest.avoid.maps.

Public release downloads need no GitHub account or token. In Obtainium, add https://github.com/avoid-quest/maps as a GitHub source and select avoid-maps.apk if needed. Keep the existing installation when updating: compatible signing preserves favourites. Obtainium access and upgrade preservation require a device test.

Builds with local diagnostics read version/code from the embedded Expo configuration. The build script embeds the Git revision when the checkout has no uncommitted tracked changes or unignored untracked files. Any such change, including documentation, reports development. The diagnostics report uses these public build identifiers and excludes device identifiers. Native dependency changes such as the clipboard module require a new APK. The GTT timetable store adds expo-sqlite (bundled SQLite), expo-crypto (SHA-256), expo-network (Wi-Fi-only preference; merges the normal ACCESS_NETWORK_STATE and ACCESS_WIFI_STATE permissions), uses expo-asset (added with the brand assets below) to load the bundled package file and expo-file-system for package staging; fflate (pure JavaScript, MIT, no native code) inflates GTT ZIP members for the trip-ID remap; none pulls Google Play services. Verify the merged manifest and Google-free launch after rebuilding.

Acceptance without Google Play services

  1. Install into a profile without Google Play; launch with Metro stopped. The map renders over the network.
  2. Deny location, search a public place and a food category, open a place and plan a route using the map center as origin.
  3. Grant approximate location, then precise location outdoors. Confirm the locate button settles or gives a useful timeout and continues to work after background/foreground transitions.
  4. Open transit stops and check live-feed timestamps; disconnect the network and confirm unavailable/stale wording remains honest.
  5. Save a place, close the app, relaunch, and confirm it remains saved. Install a later APK signed with the same key to verify upgrade preservation.
  6. Run the separate navigation acceptance for walking, cycling, driving and transit. Verify current precise positioning, offline Italian speech or visible missing-voice state, bounded rerouting, manual transit confirmations, notification Stop and interrupted-session handling. Inspect foreground-service/location/notification permissions, absence of background-location permission and bundled third-party notices on the final APK.

Emulator checks prove Android packaging and runtime behaviour, not physical-device GPS accuracy, lifecycle behaviour, or battery consumption. Record those device checks separately.

Position availability

Location permission authorizes a request; it does not guarantee a current fix. MapLibre's default Android engine requests platform positioning, including the network provider when available alongside GPS. A Google-free system may have no working Wi-Fi/cell positioning provider, so indoor browsing can time out even with precise permission and location enabled. Navigation listens to platform GPS and, when available, the platform fused (Android 12+) and network providers, and admits only fresh fixes within its per-mode accuracy policy; a cached position older than 15 seconds cannot start guidance.

Foreground browsing checks existing permission on launch and resume without prompting. Explicit Locate can request permission. Provider status is sampled before acquisition and after timeout: local diagnostics distinguish disabled services, GPS only, network only, both enabled, another active platform provider, and no enabled provider. These fixed codes contain no coordinates or device identifiers. An enabled provider does not establish that it can return a fix. Older native binaries without the status method continue acquisition with generic timeout wording; rebuild the APK to expose provider status.

Indoor timeouts after earlier successful fixes do not establish which platform provider stopped returning results. To diagnose missing fixes, verify a fresh outdoor fix, then compare indoor provider status and timeouts on the rebuilt APK. Browser and JVM checks cannot establish Android GPS reception or indoor positioning availability.

Dependency review

The initial SDK 54 lockfile was checked with npm audit and compatible fixes applied. The web-only MapLibre renderer was updated to 6.13.0 and protobufjs to 8.8.0 to remove critical advisories; the native MapLibre package remains pinned separately. For the original v0.1.0 lockfile on 2026-10-11, npm reported 44 advisory paths (26 high, 16 moderate, 2 low), mostly inherited build/CLI CSS, image, glob, signing and source-map tooling. npm audit fix --force proposes incompatible framework changes, so those changes were not applied mechanically. Treat untrusted build input and development servers accordingly; this is not a claim that the entire dependency graph is vulnerability-free. These historical counts do not describe the later Bun lockfile. Recheck the active lockfile with bun audit when updating Expo or its toolchain.

Brand assets add two Expo modules and enable one existing module's config plugin: expo-font (already a dependency; its config plugin now embeds the bundled Geist and Mona Sans TTFs as Android XML font families), expo-splash-screen (black splash with the brand mark; AndroidX core-splashscreen), and expo-asset (resolves the bundled font URLs that src/theme/fonts.web.ts declares with @font-face on the web). Their Android dependencies are AndroidX and React Native only; none pulls Google Play services. @resvg/resvg-js is a development-only renderer for scripts/render-brand-assets.mjs and is not part of the app. After changing the mark, run the script and commit the PNGs; node scripts/render-brand-assets.mjs --check fails when they are stale. Fonts and their OFL-1.1 texts are listed in assets/fonts/README.md.

The planner's time chip uses @react-native-community/datetimepicker 8.4.7 (SDK 54 core has no date/time dialog and @expo/ui is beta). SDK 54 lists exactly 8.4.4, but its Kotlin sources call getCurrentActivity(), which the Kotlin 2.2.20 pinned by the navigation plugin rejects (MaterialDatePickerModule.kt/MaterialTimePickerModule.kt: "Function invocation 'getCurrentActivity()' expected"); 8.4.5 and later use reactApplicationContext.currentActivity. The package is therefore listed in expo.install.exclude so bun run doctor accepts the exact 8.4.7 pin; revisit when the SDK's expected version catches up. Only the imperative DateTimePickerAndroid.open API is used, with timeZoneName: 'Europe/Rome'; it shows the platform DatePickerDialog/TimePickerDialog. Its Android library depends on AndroidX core-ktx and com.google.android.material:material 1.12.0 (Material Components, Apache-2.0, a UI library with no Google Play services, location or network use). No config plugin is needed for the default dialogs, so none is added. It requires a rebuilt APK; verify the merged dependency graph and manifest stay free of com.google.android.gms and add no permission. The web preview uses the browser's date/time input instead.

Apri in un’altra app calls Linking.openURL with a geo: URI. It needs no <queries> entry because the app never asks which handlers exist; with no map app installed the failure is reported in Italian.