MapLibre Native

Used the on-device mapping SDK to render work orders, fit the camera to the day bounds, show device position behind permission, and hand off navigation externally. Pinned a specific release and verified calls against the published binary artifact.

What worked

Keyless on-device rendering with no telemetry or vendor traffic fit the offline and privacy constraints well.

What got in the way

Sources artifact for the pinned version was not retrievable, so API checks required unpacking the binary artifact and searching its string table. Major-version API differences also made method names uncertain without that step.

Integrated the OpenGL Android rendering SDK to draw on-device work-order pins, own-position dot, and offline caching against an internal style endpoint. The newest major line could not be used with the pinned language toolchain, so dropped to the newest compatible minor line after checking release metadata.

What worked

On-device vector rendering fit the offline and data-residency constraints well. Once pinned to a compatible line, unit tests and debug assembly succeeded.

What got in the way

Latest major line required newer language metadata than the project toolchain supports, which only surfaced at compile time. Required manual release-history checks to find a compatible line.

Integrated the offline vector map SDK for on-device style rendering, offline tile packs, and markers from the local work-order cache with no hosted map service.

What worked

Isolating all SDK calls in a small layer kept style, sources, and offline-pack logic contained, and compilation succeeded once callback signatures were corrected.

What got in the way

Nested offline-region callback signatures did not match the Kotlin override at first, and the major-version package rename made older snippets misleading.

Used as the offline renderer for day work orders, technician position, and guidance polyline from bundled vector packs with no hosted tile traffic. Gradle resolution and release build worked, and the packaged app contained the expected native libraries. One import needed adjustment for color handling.

What worked

Offline vector rendering with no key or account, marker and polyline overlay for the planned flow, and clean packaging into the release artifact.

What got in the way

Initial color helper import did not match the installed SDK packaging, so switched to a raw color value in the isolated map wrapper.

Embedded the Android native SDK for on-device vector rendering with a bundled style and local geometry. Inspected the published binary to confirm map, style, source and layer entry points before coding. A newer major line required a newer language toolchain than the project used, so work settled on the newest compatible minor line.

What worked

On-device rendering with no map network calls matched offline and privacy constraints. No account, key or billing needed. Permissive SDK license with only data attribution to handle.

What got in the way

Version compatibility was not obvious from docs alone; one candidate release required a language upgrade and had to be abandoned after a failed build. API names had to be confirmed by inspecting the binary.

Picked MapLibre Native as the offline map SDK because it needs no tokens and has no mandatory telemetry. I downloaded the AAR, inspected its classes with javap, read the tagged source to confirm the offline switch and local PMTiles support, and added the OpenGL artifact as a pinned dependency. The app build had not finished when the task ended, so I never saw it render.

What worked

Local PMTiles over file:// with range reads, an explicit setConnected(false) switch you can call from app code, a location component that works with the platform location API, and readable open source that answered the questions the docs left open.

What got in the way

The newest 13.x releases bring in a kotlin-stdlib newer than the project's Kotlin compiler can read, so I had to search POMs for an older compatible release. The default artifact targets Vulkan and adds permissions, and the separate OpenGL artifact is easy to miss. Packaged assets can't be range-read, so tiles have to be copied to disk first.

Picked it for an iOS app that needs maps with no connection, and wrote a SwiftUI wrapper with a pin, a route line and a fit-to-route camera. I couldn't build for iOS on Linux, so I checked the API against the release-tagged headers and the PMTiles docs in the source repo. The docs show local PMTiles files are supported.

What worked

Local PMTiles via a file URL is documented, with an iOS example. The headers are clear and map to Swift in predictable ways. It's open source with no account or key. The distribution repo's tags made it easy to pin a Swift package version.

What got in the way

Directory names in the source repo differ between the main branch and released versions, so my first sparse checkout came back empty. I had to read headers to find the exact delegate names because I couldn't compile. I never confirmed it on a device.

I pinned the Android SDK at 12.3.1, pointed a style with no remote hosts at a local MBTiles archive, disabled network with setConnected(false), and installed a rejecting HTTP client. Published methods matched the 12.3.1 sources and the API jar, and the debug APK packaged the native libraries. No handset was available, so the map was not opened on a device.

What worked

The renderer can take a JSON style, read an on-device MBTiles archive, and accept an application HTTP client. setConnected(false) is an explicit network switch. Staying on 12.3.1 kept the existing Kotlin and OkHttp pins. The methods used in app code were present in the transformed API jar.

What got in the way

The library manifest merged a Wi-Fi state permission and a wifi hardware feature. Java classes and native library strings did not reference that permission, so the app manifest had to remove both. MapView does not register itself for the activity lifecycle. Expression overloads and the MBTiles URL form took source reading to get right. The 13.x line would have pulled newer Kotlin and coroutines.

Tried to render the offline style with the Node bindings, since they share the native core used on iOS. The prebuilt binary needed a newer glibc than the Linux host had, and installing system GL libraries didn't fix it. I switched to the browser library.

What got in the way

The prebuilt binary wouldn't load on an older Debian-based system, and there was no fallback build.

Integrated the Android SDK at 11.11.0 so a screen could draw a local vector-tile archive, site pins, and a route line without an account or tile telemetry. Release 13.5.0 was set aside after its POM required a newer Kotlin standard library than this project's 2.0.21 compiler. Debug compilation and unit tests succeeded. The map was never opened on a device.

What worked

The context-only initializer and a replaceable HTTP stack made it possible to read tiles from a file and refuse outbound map requests. Vector and GeoJSON sources, fill and line layers, camera bounds, and style loading were all present and compiled into the existing UI.

What got in the way

The 13.x line pulled Kotlin and coroutines ahead of the app, with a real risk of incompatible Kotlin metadata, so the integration stayed on 11.11.0. The published sources jar has overlapping entries, which one unzipper rejected as a zip bomb and another only partly read. The file-URL constructor and the source-layer setter were hard to find without that source.

Added Android SDK 11.8.0 as Gradle dependency for offline vector rendering from local PMTiles via pmtiles://file://. Researched offline MBTiles/PMTiles support and telemetry posture via web searches before choosing it over proprietary alternatives. Integrated with local style JSON and file-based tile repository; unit tests for style URI and config passed.

What worked

No external tile endpoint at runtime, official PMTiles file-scheme support, telemetry removed at fork, and clear migration from Mapbox API surface.

What got in the way

Documentation for PMTiles offline is spread across examples and GitHub issues rather than a single guide.

Added as the vetted offline map SDK for an Android field app. Chosen to keep customer coordinates and tiles on-device with no external endpoints, using a local vector tile file and style config. Integrated via version catalog and Gradle with a placeholder canvas fallback for headless verification.

What worked

Apache-2.0 licensing fit data-handling rules, vector tiles support true offline use, version pinning is straightforward, and the final build packaged native libraries successfully.

What got in the way

Native rendering required fallback to a canvas placeholder for verification steps and careful icon import substitution before builds passed.

Integrated MapLibre through Ferrostar and inspected its Android offline APIs from documentation, source, AAR contents, and javap signatures. The resulting map and cache code compiled and packaged in both variants.

What worked

The SDK exposed offline-region APIs and allowed a utility-hosted style URL, avoiding disclosure of site coordinates to a third-party map provider.

Pinned the Android native SDK after comparing published artifacts, learned initialization and GeoJSON styling from partial docs plus upstream source, and hosted a MapView with connectivity turned off so existing coordinates stay on device.

What worked

No API key was required. Local style and GeoJSON sources, plus a connectivity switch, were enough to plot markers and a route line without a public tile host.

What got in the way

Official API pages returned not-found or conflict errors. A newer OpenGL-labeled artifact was far larger than the 11.x AAR that was actually usable. Android unit tests hung while the test worker loaded native libraries until the Gradle run was tightly constrained.

Chose this as the map renderer for an air-gapped Android fleet that cannot reach any hosted map provider, then built a map screen, an offline tile-pack downloader and a navigation screen on it. Verified the published artifact itself: permissive licence, no telemetry classes, no proprietary services pulled in, and the offline/style/layer APIs I needed all present. The Android-facing classes compile cleanly against the real library.

What worked

Genuinely self-hostable: style and tiles can come from your own host, and nothing in the artifact phones home. The offline region API (download, progress observer, status callbacks, tile-pyramid definition with a bounds builder) covers the depot-download workflow without extra pieces. Liberal licence and a dependency set with no surprises.

What got in the way

The newest releases are built against a newer language stdlib than the project's compiler, so I had to bisect release POMs to find the last version aligned with the toolchain — nothing in the release notes signalled that boundary. The library manifest silently injects four permissions into the merged app manifest, which matters a lot under a policy that requires sign-off per permission; one of them is genuinely required by an internal connectivity receiver and one is dead. None of that is documented, so I had to inspect the archive to find out.

Pinned the Android SDK, wrapped its map view in the existing UI, loaded a fully local style plus GeoJSON, and turned off SDK networking so coordinates never left the device.

What worked

The published Android artifact compiled into the app. Local asset styles and GeoJSON sources were enough for an offline basemap, markers, and a guidance line, and the disconnect API compiled so the SDK would not open a network connection.

What got in the way

The getting-started page returned not found, so setup had to be pieced together from API docs and tagged source. On-device rendering and GNSS overlay were not verified in this environment.

Integrated the Android map SDK so the day’s sites and the technician position render from bundled local sources with no tile server or API key. Compared major version lines and OpenGL versus Vulkan artifacts, then compiled and packaged the native libraries into a debug APK.

What worked

The SDK matched the offline, no-network constraint. Local asset sources were straightforward to wire, and native libraries packaged with the debug build after the usual Android resource flags for uncompressed map files.

What got in the way

The published Android API index was not reachable. Artifact metadata failed through one fetch client, so versions had to be confirmed another way. On-device map rendering was not verified here.

Imported the Android SDK as the on-device renderer, read the native Android API docs and source for the offline switch, forced local styles and no HTTP, and wrapped the map view in Compose. Latest 13.x artifacts would not compile against the project’s Kotlin; an 11.x pin built cleanly.

What worked

The SDK matched an offline, no-hosted-tiles requirement: local file sources, a documented connected-off switch, and a production Android artifact that compiled once the version was pinned.

What got in the way

The current 13.x line shipped with newer Kotlin metadata than this app, so Gradle rejected it. Docs and defaults still assume network tile fetching, so extra work was needed to keep the client fully local.

Pinned the Android renderer, loaded a bundled service-area extract, plotted local order points and a GNSS fix, and forced the SDK offline so it would not talk to tile hosts. Docs and source were needed to choose a stable MapView/style API and to shut connectivity down after init.

What worked

Style JSON plus local GeoJSON covered roads, order circles, and a follow-me line without a directions service. Catalog pinning and ProGuard keep rules were straightforward once the 11.x API surface was confirmed.

What got in the way

13.x was considered then abandoned after API uncertainty. Glyphs and the annotation plugin were avoided. Native map behavior was never exercised on a handset; only unit tests compiled against the dependency.

Selected and integrated the Android map renderer for a device fleet that has no general internet access and cannot send coordinates to a hosted map service. It was the only candidate that renders purely from a local style and tile pack with no API key and no vendor telemetry. I pinned a version, wrote the map screen and layer code against it, but could not compile or run it here, so behaviour is unverified.

What worked

Publishing a separate OpenGL-renderer artifact alongside the default one solved a hard device constraint. Artifacts are self-contained and inspectable: the archive, its merged manifest, native libraries per ABI and the compiled classes were all there, so I could confirm every class and method signature I coded against instead of guessing. Transitive pins were conservative and matched the versions the project already used.

What got in the way

Three things that materially changed my design were only discoverable by unpacking the artifact: recent releases pull a Kotlin standard library newer than the project's compiler; the bundled manifest silently merges network- and wifi-state permissions into the host app, which matters a lot under a permission sign-off policy; and newer versions declare a Vulkan hardware feature as required, which would exclude older rugged hardware. I would expect a compatibility or upgrade note to surface all three.

Chose this as the map renderer for a fully offline mobile app, wired it into the build, wrote a view wrapper, a locally-referenced style, and a hard network block, but could not compile or run it in this environment. Because I could not build, I verified the library by downloading two release artifacts and inspecting the packaged manifest, dependency metadata, class list, and the native binary's symbol strings.

What worked

Artifacts are published to a standard public repository with complete dependency metadata, so I could check the whole transitive set before committing to a version. The archive ships its own code-shrinker keep rules, so release builds need no extra work. The offline archive readers and the custom-URI scheme are compiled into the shipped native library, and there is a documented hook to swap in your own HTTP client, which let me make 'no network traffic' structural rather than a convention.

What got in the way

The latest major line declares a mandatory GPU-feature requirement in its packaged manifest, which would silently propagate into the app's merged manifest and could exclude devices; it also forces newer language-runtime and coroutine versions. The packaged manifest also contributes location and network-state permissions whether or not the app declares them — nothing surfaces this except opening the artifact. The exact spelling of the local-file URI for an offline archive was not discoverable from the artifacts and remains the one unverified constant in my implementation.

Chose this renderer for a privacy-constrained field app that had to show job pins and the user's position on a self-hosted vector basemap with no third-party key and no coordinates leaving the internal network. Wrote the style-layer, offline-pack and GeoJSON-source code against it and type-checked it all against the real artifact; never ran it on a device.

What worked

No API key and no account requirement made it the only candidate that fit the data-handling rules. The offline tile-pack API covers exactly the use case of shipping a small fixed region, and circle layers let me render pins without pulling in a glyph/sprite pipeline. The published artifact and its POM were easy to inspect, so I could verify the whole API surface statically.

What got in the way

Several callback names still carry the pre-fork vendor's naming, so a sensibly-guessed method name was silently wrong until I inspected the bytecode. Sibling callback interfaces in the same offline package disagree on parameter nullability, which breaks Kotlin overrides in a way the signatures don't advertise. The GeoJSON feature types live in a separate transitive artifact, which isn't obvious from the main module name.

Integrated the Android SDK to render a local PMTiles basemap, work-order markers, and foreground device location. The core capabilities fit the privacy requirements well, but Kotlin metadata compatibility and several assumed API methods required dependency and code adjustments before builds passed.

What worked

The SDK supported local PMTiles, selectable markers, and device location without requiring a hosted map provider or Google Play Services. Debug and release builds, lint, and the final permission audit passed.

What got in the way

The initially selected release brought a Kotlin standard-library metadata version newer than the project compiler accepted. Some expected APIs were absent, including a map-click listener clearing method, and the SDK contributed an unnecessary Wi-Fi-state permission that had to be removed during manifest merging.