AdminConsole
Tutorials/Intermediate
Intermediate50 minCordova

Ship a Mappls map in Cordova and Ionic

Separate web and native configuration, wait for device readiness, and clean up plugin state safely.

By the endA hybrid map screen with lifecycle-safe native bridge handling.
Real-world scenario

Build against an explicit contract

A Cordova/Ionic application needs native Mappls capability while JavaScript, WebView, and native plugin lifecycles remain independently owned.

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

Define the user and system contract

A Cordova/Ionic application needs native Mappls capability while JavaScript, WebView, and native plugin lifecycles remain independently owned. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Align plugin and native projects

Use the documented plugin version, apply Android/iOS credentials and permissions in platform configuration, and rebuild generated native projects after config changes.

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

Wait for device and view readiness

Call native features only after `deviceready`, serialize bridge inputs, avoid duplicate listeners across page navigation, and remove the native view before DOM ownership ends.

Step 4

Design a browser fallback

Keep search/place identity in shared application state and provide a Web Maps or deep-link route for unsupported devices and plugin initialization failure.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when re-entering the page creates one native view; both native projects pass release configuration; plugin failure has a usable fallback. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

JavaScript calls before device readiness

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

native view survives page teardown

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

platform/plugin version mismatch

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

re-entering the page creates one native viewboth native projects pass release configurationplugin failure has a usable fallback

Cordova production checks

Supported status is verified before new developmentToolchain and plugin versions are frozenBridge inputs are validated and boundedA tested migration and rollback path exists
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.

Study the complete Consented address verification state machine
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.