Configuration
Pass configuration to window.GreetingCardBuilder(config). Create one instance
and reuse it.
Builder and iframe
| Field | Type | Default | Behavior |
|---|---|---|---|
baseUrl | string | loader script origin | Builder origin. Required when the loader URL cannot be discovered. |
hostOrigin | string | window.location.origin | Trusted host origin sent to the iframe. Required for opaque origins such as file: pages. |
runtime | 'legacy' | 'yuzu' | 'legacy' | Selects /boot or /v2/boot. yuzuGcbEnabled: true in init data also selects Yuzu. |
builderPath | string | runtime route | Overrides the iframe path. Use only when Giftie supplies a custom route. |
embedMode | string | 'shopify' | Builder embed mode sent in the iframe URL. |
frameParams | Record<string, string | number | boolean> | none | Adds primitive query parameters to the iframe URL. |
initData | object | none | Initial card data sent after the builder reports ready. |
autoPreload | boolean | false | Creates the iframe during an idle callback without opening the modal. |
When the script is served separately from the builder, set baseUrl or set
window.GIFTIE_GCB_BASE_URL before loading the script.
URL configuration is not a secret channel. Do not put access tokens, personal
data, customer messages, or private order fields in frameParams.
Modal behavior
| Field | Type | Default | Behavior |
|---|---|---|---|
closeOnComplete | boolean | true | Closes after onCardComplete unless set to false. |
closeOnBackdrop | boolean | false | Allows a click on the dialog backdrop to cancel and close. |
ariaLabel | string | 'Greeting Card Builder' | Accessible label for the modal dialog. |
iframeTitle | string | 'Greeting Card Builder' | Accessible iframe title. |
modalPadding | CSS length | '0' | Padding around the iframe on desktop. Forced to 0 below 768 px. |
borderRadius | CSS length | '0' | Iframe radius on desktop. Forced to 0 below 768 px. |
Recording bridge
The card builder can ask the host to open Giftie's video/audio recording SDK.
| Field | Type | Default | Behavior |
|---|---|---|---|
widgetLoaderUrl | string | none | Recording SDK loader URL. Required when the card can add video or audio and window.Giftie is not already present. |
widgetBaseUrl | string | none | Optional recording widget base URL, assigned before loading its script. |
The card SDK creates one recording instance lazily and returns a saved recording
code to the card iframe. See onRecordingSaved below if the host also needs the
recording result.
Callbacks
| Field | Signature | When it runs |
|---|---|---|
onOpen | ({ iframe, url }) => void | The modal has opened. |
onLoad | ({ iframe, url }) => void | The iframe's browser load event fires. |
onReady | (data) => void | The trusted iframe first reports gm/ready. |
onInit | (data) => void | The SDK sends initialization data, including its generated requestId. |
onInitApplied | (data) => void | The builder acknowledges that initialization was applied. |
onCardComplete | (data) => void | The builder emits its completion payload. |
onCancel | (data) => void | Escape, backdrop, or builder cancellation occurs. |
onClose | ({ reason }) => void | The modal closes. |
onAnalytics | (data) => void | The builder emits an analytics event. |
onRecordingSaved | (result) => void | The nested recording widget saves video or audio. |
onError | (error) => void | The loader reports a structured host-side error. |
Callback exceptions are caught and logged so they do not break the SDK lifecycle. Returned promises are not awaited; catch asynchronous failures inside your callback.