AdminConsole
Quickstarts/React Native
React NativePublic Source30 minutes

Bridge one map feature across Android and iOS

a typed shared map feature with separately verified native halves

Public Source

What this path can prove

The public wrapper is sample-classified. Confirm React Native, wrapper, New Architecture status, Gradle/Kotlin, Xcode/Swift, and underlying native Mappls versions as one release unit.

Credential boundary

Configure Android and iOS app credentials independently and keep privileged calls on a backend. JavaScript configuration is not a secret store.

current
Mappls React Native SDKmappls-react-native-sdk
Before the timer starts

Prepare the exact environment

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

  1. 01

    A clean React Native TypeScript app

  2. 02

    Approved wrapper/native version matrix

  3. 03

    Separate restricted Android and iOS app credentials

  4. 04

    Physical Android and iOS devices

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 React Native package, endpoint, toolchain, region, and account entitlement before installing anything. The public wrapper is sample-classified. Confirm React Native, wrapper, New Architecture status, Gradle/Kotlin, Xcode/Swift, and underlying native Mappls versions as one release unit.

  2. 02

    Create a clean boundary

    Complete both native project setups before importing the JavaScript component, then normalize camera, feature identity, readiness, errors, and cleanup behind a typed application wrapper.

  3. 03

    Build one useful result

    Render one selected place, throttle high-frequency camera events, and retain an unsubscribe handle for every native subscription.

  4. 04

    Run the release path

    Build both release variants, mount/unmount repeatedly, background and restore, rotate Android, pressure iOS memory, and deny permissions independently.

  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.

$ npm install

$ npm run android

$ npm run ios

$ npm 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.

React Native first-success scaffold
export type Camera = { center: [number, number]; zoom: number };
export type MapEvent = { type: "ready" } | { type: "camera"; value: Camera } | { type: "error"; code: string };

export interface NativeMapPort {
  configure(styleId: string): Promise<void>;
  showPlace(place: { id: string; coordinate: [number, number] }): Promise<void>;
  subscribe(listener: (event: MapEvent) => void): () => void;
  dispose(): Promise<void>;
}
Definition of first success

Verify behavior, not screenshots

  1. 1

    Android and iOS return the same application-level selected ID while platform-specific failures remain visible and attributable.

  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 productionWrapper/native matrix is pinnedBoth release builds are provenBridge traffic is boundedUnmount disposes every native resourceNative and wrapper releases are compatibleHigh-frequency events are throttled before crossing the bridgeUnmount releases native views and listenersPlatform-specific behavior is documented, not hidden
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
One platform works while the other reports missing native view/module

Only one native project, dependency graph, architecture mode, autolinking step, credential restriction, or build cache is correct.

Treat each platform as its own build: inspect resolved native dependencies and registration, clean only scoped build output, and prove the native example before the shared wrapper.

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.