AdminConsole
Tutorials/Advanced
Advanced85 minWidgets

Operate widgets as untrusted lifecycle surfaces

Validate origin and schema, separate candidate from commit, recover blocked embeds, preserve accessibility, and retire safely.

By the endA restart-safe host journey with exact-origin validation and a complete non-widget fallback.
Real-world scenario

Build against an explicit contract

A host application embeds a provider-owned surface but must retain validation, persistence, accessibility, recovery, and business submission authority.

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 application embeds a provider-owned surface but must retain validation, persistence, accessibility, recovery, and business submission authority. Record the region, data freshness, latency budget, privacy purpose, credential owner, and fallback before choosing an SDK or endpoint.

Step 2

Constrain the trust boundary

Pin the documented origin/component/release, CSP and frame policy, exact message origin, versioned allow-list schema, credential class, entitlement, and one host generation.

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

Separate candidate from commitment

Treat every callback/message as untrusted candidate evidence, copy only bounded identity, require a deliberate user commit, invalidate selection after host edits, and persist with idempotency and expected version.

Step 4

Operate failure and retirement

Handle blocked script/frame, timeout, denied access, duplicate/late messages, back navigation, bfcache, unmount, dependency upgrade, accessibility focus, useful manual fallback, telemetry minimization, and rollback.

Step 5

Prove the production behavior

Automate the happy path and every named failure. The release is ready only when wrong-origin and unknown-schema input changes no state; candidate receipt cannot submit the business record; fallback supports keyboard and screen-reader completion; unmount and rollback leave no active generation. Capture provider request identity without logging credentials or unnecessary precise location.

Recovery design

Failure modes you must exercise

CSP or browser blocks the widget

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

message contract changes without version negotiation

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

late callback targets an edited or submitted host record

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

wrong-origin and unknown-schema input changes no statecandidate receipt cannot submit the business recordfallback supports keyboard and screen-reader completionunmount and rollback leave no active generation

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 Connected fleet trip 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.