AdminConsole
Quickstarts/Deep links
Deep linksPublic Source10 minutes

Ship one zero-SDK Mappls hand-off

a place link that reaches the same intent across app and browser fallbacks

Public Source

What this path can prove

Use the exact link shape documented by the current App Widgets source. The scaffold below deliberately receives that approved base rather than inventing an undocumented path.

Credential boundary

Deep links contain no credential. Put only bounded non-sensitive intent in the URL; precise private/user data and server secrets must never become query parameters.

current
Mappls App Widgetsmappls-app-widgets
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 stable Mappls place identity or validated destination

  2. 02

    The exact documented link template

  3. 03

    Installed/uninstalled Android and iOS test devices

  4. 04

    Browser, messaging, email, and QR test channels

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 Deep links package, endpoint, toolchain, region, and account entitlement before installing anything. Use the exact link shape documented by the current App Widgets source. The scaffold below deliberately receives that approved base rather than inventing an undocumented path.

  2. 02

    Create a clean boundary

    Store the documented allow-listed base and construct URL components with the platform URL library; never concatenate user input or allow it to change origin/path shape.

  3. 03

    Build one useful result

    Render human-readable destination context, the hand-off link, and a copyable/browser fallback that preserve the same stable intent.

  4. 04

    Run the release path

    Test installed/uninstalled app, mobile/desktop browsers, messaging, email, QR, in-app webviews, offline state, and rewritten links.

  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 test

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

Deep links first-success scaffold
export function buildMapplsHandoff(approvedBase, placeId) {
  const url = new URL(approvedBase);
  if (url.protocol !== "https:" || !/^(?:www.)?mappls.com$/.test(url.hostname)) throw new Error("unapproved_base");
  if (!/^[A-Za-z0-9_-]{3,40}$/.test(placeId)) throw new Error("invalid_place_id");
  url.searchParams.set("place", placeId); // Use only the parameter name confirmed by the source guide.
  return url.toString();
}
Definition of first success

Verify behavior, not screenshots

  1. 1

    Every supported channel reaches the same destination intent or a useful visible fallback without sensitive query data.

  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 productionNo private data is encodedAll values are validated and encodedApp/browser intent matchesRedirect domains are allow-listedUser or confidential data never appears in query parametersAll variable values are encoded and length-boundedApp and browser fallbacks reach the same intentRedirect and campaign domains are allow-listed and monitored
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
A channel opens a generic page or different destination

The association, link shape, encoding, redirector, app installation state, or channel rewriting altered the documented intent.

Compare the final URL components without private data, bypass unapproved redirectors, and retest installed/uninstalled fallback against the exact guide.

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.

Open the deep-link lab