Lifecycle
Loading and readiness
The SDK has three distinct states:
isLoaded()becomestruewhen the iframe's browserloadevent fires.isReady()becomestrueafter a trusted message from that exact iframe and builder origin reportsgm/ready.onInitAppliedruns only after the builder applies the initialization data.
Use onInitApplied when host UI must know that the requested card is active.
Neither onLoad nor onReady confirms that card initialization succeeded.
Initialization delivery
open(initData), preload(initData), and config.initData all set pending
initialization data. The SDK shallow-copies the object, adds an incrementing
requestId, and sends it once the iframe is ready.
The SDK accepts only messages whose source is the current iframe and whose origin exactly matches the iframe origin.
Completion
When the builder completes:
onCardComplete(payload)runs.- The modal closes with reason
'complete'unlesscloseOnCompleteisfalse. onClose({ reason: 'complete' })runs when automatic close is enabled.
The current embedded builder may then emit its close message after the
completion message. In that case onCancel also receives the builder message,
but the already-closed modal is not closed a second time. Treat
onCardComplete, not onCancel, as the authoritative successful outcome.
Callbacks are invoked synchronously, but returned promises are not awaited. Contain errors and catch promise rejections inside each callback.
Cancellation and close reasons
| Path | onCancel data | onClose reason |
|---|---|---|
builder.close() | not called | 'api' |
builder.close('route-change') | not called | 'route-change' |
| Escape key | { reason: 'escape' } | 'escape' |
| Backdrop click | { reason: 'backdrop' } | 'backdrop' |
| Builder cancellation | builder data or { reason: 'builder' } | 'cancel' |
| Completion | may receive the builder's follow-up close message | 'complete' |
destroy() while open | not called | 'destroy' |
Escape is handled by the native dialog cancel event. Backdrop cancellation is
available only when closeOnBackdrop: true.
Reopening
Closing keeps the iframe available for reuse. The SDK resets its open state but
does not destroy the loaded card. Pass new init data to open() or preload()
when the next card differs.
Use destroy() when reuse is not wanted. It removes the iframe, dialog, and
window message listener and also closes the nested recording instance.