AdminConsole
Tutorials/Beginner
Beginner25 minWidgets + Web

Embed a place picker widget

Mount a bounded widget, synchronize selection with your form, and preserve the selected Mappls Pin.

By the endAn accessible embedded place picker with explicit host-page ownership.
Real-world scenario

Build against an explicit contract

A host form needs an embedded Mappls place experience while retaining control of validation, focus, persistence, and submission.

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

Define the user and system contract

A host form needs an embedded Mappls place experience while retaining control of validation, focus, persistence, and submission. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Set the trust boundary

Load only the documented HTTPS widget origin, restrict browser configuration to the exact host, define allowed messages/events, and give the frame/container a clear title and size.

App Widgets & Deep Links · SDK or product slice
<a
  href="https://mappls.com/MMI000"
  target="_blank"
  rel="noopener noreferrer"
>
  Open this place in Mappls
</a>
Step 3

Normalize one terminal result

Bind one launch generation to the host lifecycle, treat widget output as an untrusted candidate, validate exact origin and schema, retain only Mappls Pin plus bounded label, and ignore late or duplicate results.

Step 4

Commit selection deliberately

Keep candidate, accepted selection, and submitted record as separate states. Persist application selection only after a user decision with idempotency key and expected session version.

Step 5

Invalidate stale identity

When host-owned address text changes, clear candidate and accepted Mappls Pin, return to draft, and block submit until the user selects again.

Step 6

Integrate fallback and accessibility

Return focus after selection, cancel, or failure; mirror the accepted place in native form controls; announce errors; and keep a complete non-widget search/manual fallback.

Step 7

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when unexpected origins and opaque messages are ignored; a candidate cannot submit the form by itself; host edits invalidate stale selection; keyboard users can complete widget and fallback paths. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

widget script or frame blocked

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

message schema/version changes

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

duplicate or late terminal callback

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

host text edited after widget selection

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

unexpected origins and opaque messages are ignoreda candidate cannot submit the form by itselfhost edits invalidate stale selectionkeyboard users can complete widget and fallback paths

Widgets production checks

Embedding 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
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.