Greeting Card Builder SDK

Errors and limitations

Handle Greeting Card Builder loader errors and current lifecycle limitations.

Error callback

onError receives an Error with a loader-specific code when the SDK can report a structured failure.

const builder = window.GreetingCardBuilder({
  onError(error) {
    console.error(error.code, error.message)
  },
})

Code	Meaning
`dialog_open_failed`	The native modal could not open; the loader falls back to the `open` attribute.
`dialog_close_failed`	The native dialog close failed; the loader removes the `open` attribute.
`init_message_failed`	The SDK could not send initialization data to the iframe.
`init_failed`	The builder rejected initialization. Its message is exposed on the error.
`widget_loader_missing`	A recording was requested but no recording loader URL was configured.
`widget_loader_failed`	The recording SDK script failed to load.
`widget_factory_missing`	The recording script loaded without exposing `window.Giftie`.
`widget_open_failed`	The nested recording widget could not open.

Callback errors are logged as [GreetingCardBuilder] <callback> callback failed; they are not forwarded to onError.

Some failures occur before an SDK instance can report them:

If the loader script is blocked or unavailable, window.GreetingCardBuilder is not created. Handle the script error event.
An opaque host origin throws during iframe creation unless hostOrigin is explicitly configured.
An invalid or missing builder base URL throws from open(), preload(), or URL-changing updateConfig().
onLoad proves only that the browser loaded the iframe document. Use onInitApplied to confirm initialization.

There is no official npm package or bundled TypeScript declaration.
The loader does not expose a ready promise.
Returned callback promises are not awaited.
There is no built-in initialization timeout. Hosts that require one should start it on onOpen and clear it on onInitApplied.
frameParams are placed in the iframe URL and must not contain sensitive data.
The loader owns presentation and transport only. Catalogue lookup, session authorization, Shopify cart mutation, and host application state remain integration responsibilities.
Calling open(), preload(), or updateConfig() after destroy() throws.

Contact Giftie before depending on unlisted message types, iframe routes, query parameters, or payload fields.

Data contract

Supply legacy or Yuzu card initialization data and handle the completion payload.

Errors and lifecycle limitations

Handle current browser SDK failures and lifecycle limitations.