AdminConsole
Quickstarts/Android
AndroidPublic Source25 minutes

Create a lifecycle-safe Android map

a native map screen that survives recreation and permission denial

Public Source

What this path can prove

The public repositories are sample-classified evidence; confirm Maven coordinates, BoM, AGP/Kotlin, min/target SDK, and supported release with Mappls.

Credential boundary

Use only the documented Android credential configuration restricted to the package and signing identity. Server credentials never belong in the APK.

current
Mappls Android SDKmappls-android-sdk
sample
Mappls Vector Map Android SDK JetPack Composemappls-android-compose-demo
Before the timer starts

Prepare the exact environment

Do not count account, package, build-host, or device discovery as hidden quickstart work.

  1. 01

    Android Studio and a clean Kotlin app

  2. 02

    Confirmed AGP, Kotlin, minSdk, and targetSdk matrix

  3. 03

    A package/signature-restricted non-production key

  4. 04

    At least one physical device for release validation

Five-stage path

Build one complete result

Each stage has a proof. If the proof is missing, do not advance by assumption.

  1. 01

    Confirm the source line

    Open the linked evidence and confirm the exact Android package, endpoint, toolchain, region, and account entitlement before installing anything. The public repositories are sample-classified evidence; confirm Maven coordinates, BoM, AGP/Kotlin, min/target SDK, and supported release with Mappls.

  2. 02

    Create a clean boundary

    Pin the approved SDK and native build matrix, initialize at the documented application boundary, and keep map/view references owned by one Activity, Fragment, or Compose wrapper.

  3. 03

    Build one useful result

    Render a map without requiring location permission; add an explicit user action that requests location and represents denied, approximate, stale, and unavailable fixes separately.

  4. 04

    Run the release path

    Build a release variant, rotate, background, revoke permission, enable battery saver, trigger process death, and reopen the screen.

  5. 05

    Break it deliberately

    Exercise missing/denied credentials, unavailable network or runtime, invalid input, cancellation, and cleanup. Show a bounded user-safe failure while retaining a correlation identity for support.

Clean-path commands

Run what will ship

Replace documented placeholders through your environment or secret provider. Commands are scaffolds; platform signing, accounts, packages, and schemes remain project-specific.

$ ./gradlew dependencies

$ ./gradlew assembleDebug

$ ./gradlew assembleRelease

$ ./gradlew test
Application-owned seam

Start with code you can replace

The scaffold keeps provider-specific symbols and credentials behind a narrow boundary. Bind the confirmed Mappls source line inside that adapter.

Android first-success scaffold
data class CameraState(val latitude: Double, val longitude: Double, val zoom: Double)

interface MapSurface {
    suspend fun attach(saved: CameraState?)
    fun showPlace(id: String, latitude: Double, longitude: Double)
    fun save(): CameraState
    fun detach()
}

// Keep SDK classes inside the confirmed adapter; the ViewModel owns only this contract.
Definition of first success

Verify behavior, not screenshots

  1. 1

    Camera/selection state restores intentionally and no map listener or location request survives the owning lifecycle.

  2. 2

    A blocked, missing, or unentitled provider produces a useful explicit failure rather than a blank surface or fabricated result.

  3. 3

    No server credential, bearer value, precise private fixture, or provider response body appears in client bundles, logs, screenshots, or test artifacts.

  4. 4

    Resources, listeners, sessions, processes, or requests stop cleanly when the owning screen, request, or application ends.

Before productionRelease dependency matrix is reproduciblePermission denial is a complete stateProcess recreation is testedNative resources detach deterministicallyDependency versions are pinned and reproducibleLocation permission is contextual and revocableBackground work complies with current Android policySDK resources and observers are released deterministically
Fast diagnosis

When first contact fails

Keep the safe provider request identity, resolved package/runtime versions, platform logs, and exact reproduction steps. Never attach credentials or private location payloads.

SignalLikely causeNext action
Debug works but release crashes or renders nothing

Repository, dependency, shrinker, manifest, signing restriction, architecture, or resource configuration differs in release.

Resolve the release dependency graph, inspect merged manifest/resources, verify signing identity and restrictions, and test the smallest release screen on hardware.

Authentication or entitlement is rejected

The credential class, restriction, account region, host/path generation, package application, or subscribed capability does not match.

Do not try another credential shape blindly. Capture the safe status/request identity and reconcile the exact contract in the developer console or support packet.

The sample works once but not after reload, backgrounding, or a second run

Lifecycle ownership, listener disposal, token/session refresh, saved state, or a singleton initialization boundary is incomplete.

Instrument create/ready/cancel/destroy transitions and prove one owner before adding product behavior.

Keep building

From first success to a real journey

Choose the next tutorial only after the quickstart verification holds in your release path.