AdminConsole
Quickstarts/Widgets
WidgetsPublic Source20 minutes

Embed a place journey with an owned fallback

an accessible host that validates one widget result and survives widget failure

Public Source

What this path can prove

The current public Web Plugins guide spans current vector and legacy raster integration branches; source activity is not a support promise. Confirm the exact widget, script, origin, event schema, release, entitlement, and authentication line before implementation.

Credential boundary

Use only the widget/browser credential class restricted to exact origins. Validate every postMessage/callback payload and keep privileged operations on the server.

current
Mappls Web Pluginsmappls-web-plugins
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 confirmed Mappls widget and auth generation

  2. 02

    Exact host and allowed widget origins

  3. 03

    An accessible host form and manual fallback

  4. 04

    A versioned callback/message schema

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 Widgets package, endpoint, toolchain, region, and account entitlement before installing anything. The current public Web Plugins guide spans current vector and legacy raster integration branches; source activity is not a support promise. Confirm the exact widget, script, origin, event schema, release, entitlement, and authentication line before implementation.

  2. 02

    Create a clean boundary

    Load the confirmed widget only from an allow-listed origin, give its host a visible label/status/fallback, and validate origin, schema version, size, and field types before accepting events.

  3. 03

    Build one useful result

    Commit only a stable Mappls place identity plus display label into application state; invalidate it when host text changes and keep a manual/search fallback available.

  4. 04

    Run the release path

    Block the script/frame, send wrong-origin and malformed messages, resize to mobile, use keyboard/screen reader, and navigate away/back twice.

  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 dev

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

Widgets first-success scaffold
type PlaceMessage = { version: 1; type: "place.selected"; place: { id: string; label: string } };

export function acceptWidgetMessage(event: MessageEvent, allowedOrigin: string): PlaceMessage | null {
  if (event.origin !== allowedOrigin || !event.data || event.data.version !== 1) return null;
  if (event.data.type !== "place.selected" || typeof event.data.place?.id !== "string") return null;
  return event.data as PlaceMessage;
}
Definition of first success

Verify behavior, not screenshots

  1. 1

    The host submits only a validated selected identity and remains usable when the widget is slow, blocked, denied, or unavailable.

  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 productionSupported status is confirmedOrigins and payloads are validatedFallback is completeKeyboard and screen-reader behavior is testedEmbedding and content-security policies permit only required originsNo sensitive business state lives only inside the widgetLoading, failure, and unsupported-browser fallbacks existAnalytics distinguish view, engagement, completion, and hand-off
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
The widget displays but selection never reaches the form

Origin, callback name, event schema/version, load timing, or host state invalidation differs from the confirmed integration line.

Log only safe message metadata, verify exact origin/schema from the guide, reject unknown shapes, and keep the visible fallback active.

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 widget lab Compare native widgets