Quick start

The Greeting Card Builder SDK is a framework-neutral browser script exposed as window.GreetingCardBuilder. It opens Giftie's card experience in a modal iframe and sends initialization data only after the builder is ready.

It is separate from the recording SDK exposed as window.Giftie.

1. Load the script

Load the production SDK from Giftie's Greeting Card Builder domain. The loader derives the iframe origin from its own URL.

<script
  src="https://greetings-card.get-giftie.com/card-builder-loader.js"
  defer
></script>

If your site uses a Content Security Policy, allow https://greetings-card.get-giftie.com in script-src and frame-src.

2. Create one instance

Create the instance after the deferred script has loaded, then reuse it for the life of the page.

<button id="open-card-builder" type="button">Personalise card</button>

<script>
  document.addEventListener('DOMContentLoaded', () => {
    const button = document.querySelector('#open-card-builder')

    if (!button || typeof window.GreetingCardBuilder !== 'function') {
      console.error('Greeting Card Builder failed to load')
      return
    }

    const builder = window.GreetingCardBuilder({
      onCardComplete(payload) {
        console.log('Greeting card saved', payload.sessionId)
      },
      onError(error) {
        console.error(error.code, error.message)
      },
    })

    button.addEventListener('click', () => {
      builder.open({
        shop: 'example.myshopify.com',
        design: greetingCardDesign,
        shopifyVariantId: '1234567890',
      })
    })
  })
</script>

The host application must obtain greetingCardDesign and the matching Shopify variant identity through its approved Giftie integration. Do not copy design or variant values from another store.

3. Handle completion

onCardComplete receives the payload emitted by the active builder runtime. For Shopify card flows, use the returned sessionId to associate the saved card with the intended cart line. The SDK does not add a Shopify item or update your application state.

See Data contract for legacy and Yuzu initialization requirements and completion payloads.

Script-loading failures

The loader does not expose a ready promise. For dynamic loading, attach load and error listeners before appending the script, and create the instance only after load fires.

Do not initialize a second card-builder instance alongside Giftie's standard Shopify theme integration unless the integration explicitly delegates ownership of the card flow to your host application.