AdminConsole
Tutorials/Beginner
Beginner25 minAndroid

Add Mappls to an Android app

Configure the repository and BoM, initialize the SDK, and manage MapView lifecycle.

By the endA native Kotlin map screen with lifecycle-safe setup.
Real-world scenario

Build against an explicit contract

A Kotlin application needs a native map screen that survives rotation, backgrounding, process recreation, and permission denial.

A Mappls developer projectA restricted Android applicationFixture data with no production credentialsA request, aggregate, or correlation ID strategy
Step 1

Define the user and system contract

A Kotlin application needs a native map screen that survives rotation, backgrounding, process recreation, and permission denial. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Configure the native boundary

Use the documented repository and BoM, inject platform credentials through build configuration, and keep the release key restricted to the approved package and signing identity.

Maps · SDK or product slice
<!doctype html>
<html>
  <head>
    <script src="https://sdk.mappls.com/map/sdk/web?v=3.0&access_token=YOUR_STATIC_KEY"></script>
    <style>html, body, #map { height: 100%; margin: 0; }</style>
  </head>
  <body>
    <div id="map"></div>
    <script>
      const map = new mappls.Map("map", {
        center: { lat: 28.612964, lng: 77.229463 },
        zoom: 12
      });
    </script>
  </body>
</html>
Step 3

Mirror Android lifecycle

Forward creation, start, resume, pause, stop, low-memory, save-state, and destroy events to the map view exactly once.

Step 4

Own location permission separately

Render the map without location access, request permission only when the user asks for location, and distinguish denied, approximate, unavailable, and stale fixes.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when rotation preserves intended camera state; permission denial does not blank the map; destroyed activities retain no listeners. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

dependency/version mismatch

Fail fast with a typed, user-safe outcome and preserve the original request identity.

permission revoked while active

Keep the last verified state, mark freshness honestly, and retry only within the documented idempotency boundary.

activity recreated after process death

Reconcile durable local and provider evidence before declaring success or issuing a compensating command.

Never turn uncertainty into success

Timeout after a stateful command is an unknown outcome. Query by provider/idempotency identity or wait for authoritative events; do not blindly retry a new command.

Acceptance criteria

Definition of done

rotation preserves intended camera statepermission denial does not blank the mapdestroyed activities retain no listeners

Android production checks

Dependency versions are pinned and reproducibleLocation permission is contextual and revocableBackground work complies with current Android policySDK resources and observers are released deterministically
Grounded implementation

Continue from source, contracts, and a full app

These links resolve to repository-derived evidence; unsupported package names and endpoints are not filled in from guesswork.

Tutorial complete

Run it, break it, then observe it

Start with fixture credentials, execute the failure plan, and use request logs, usage, webhook evidence, and operational metrics before promoting traffic.