Tracking events for ad conversions | Sign Customiser Docs

A custom JavaScript event fires after a form submission or a successful inline Shopify cart addition. Use these events for ad tracking, CRM data, or storefront scripts.

The three tracking events in the List of events section are not available to Starter, Standard, or Pro plan families. This restriction does not apply to ShareLink events.

Note: Existing form:submitted webhook integrations continue to fire. For a new integration, read submissions from the quotes API. The API also returns submission history.

List of events

Add-to-cart events use signCustomiserProductAddedToCart.
Custom design form submission events use signCustomiserFormSubmitted.
Quote form submission events use signCustomiserQuoteSubmitted.

How to listen to these events

Add this JavaScript to your storefront theme:

document.addEventListener("signCustomiserProductAddedToCart", function (event) {
  useCartEvent(event.detail);
});

Replace useCartEvent with your tracking or integration code.

Add-to-cart event detail

{
  customiserId: "25",
  cart: {
    items: [ ... ]
  },
  domain: "your-store.myshopify.com",
  adClickIds: {
    gclid: "CjwKCAjw7p6aBhAoBhAAEiwA..."
  },
  utmParams: {
    utm_source: "google",
    utm_medium: "cpc",
    utm_campaign: "spring_sale"
  }
}

Form submission event detail

{
  customiserId: "25",
  formId: 1241,
  data: [
    {
      fieldId: "abc123",
      label: "First name",
      value: "Jane"
    }
  ],
  domain: "your-store.myshopify.com",
  adClickIds: {
    gclid: "CjwKCAjw7p6aBhAoBhAAEiwA..."
  },
  utmParams: {
    utm_source: "google",
    utm_medium: "cpc",
    utm_campaign: "spring_sale"
  }
}

formId identifies the submitted form. Use each fieldId to map a field to your CRM. Do not use the label text as an identifier.

Ad click ID tracking

All three events include adClickIds when Sign Customiser captures a supported ad click ID. The object can contain:

gclid, the Google Ads click identifier.
gbraid, an identifier for mobile and privacy-restricted cases.
wbraid, an identifier for cross-device and cookieless attribution.
fbclid, the Facebook click identifier.

The field is null if Sign Customiser did not capture a supported ad click ID.

This example sends a captured Google click ID to your conversion code:

document.addEventListener("signCustomiserProductAddedToCart", function (event) {
  var gclid = event.detail.adClickIds && event.detail.adClickIds.gclid;
  if (gclid) {
    gtag("event", "conversion", {
      send_to: "AW-XXXXXXXXX/XXXXXXX",
      transaction_id: gclid,
    });
  }
});

To send click IDs to your CRM, read Send Google Ads click IDs to your CRM.

UTM parameter tracking

All three events include utmParams when the storefront URL contains UTM parameters. The object can contain:

utm_source, the traffic source.
utm_medium, the marketing medium.
utm_campaign, the campaign name.
utm_content, the ad variation.
utm_keyword, a campaign keyword.
utm_term, the paid-search keyword.

The field is null if Sign Customiser did not capture UTM parameters for the browser session.

This example sends captured UTM data to a Google Tag Manager data layer:

document.addEventListener("signCustomiserFormSubmitted", function (event) {
  var utm = event.detail.utmParams;
  if (utm) {
    window.dataLayer = window.dataLayer || [];
    window.dataLayer.push({
      event: "sign_form_submitted",
      utm_source: utm.utm_source,
      utm_medium: utm.utm_medium,
      utm_campaign: utm.utm_campaign,
    });
  }
});

For the webhook workflow, read Track marketing campaigns with UTM parameters.

Save a ShareLink with a cart

Use ShareLink events when your theme needs the current design URL for a cart. Do not click the customer Share button. Do not remove the Share modal.

The ShareLink contract uses these events:

signCustomiserShareLinkRequested
signCustomiserShareLinkCreated
signCustomiserShareLinkFailed

The Store must be able to go live. Its plan must include sharing. Each ShareLink expires 365 days after creation.

Read Save a customer ShareLink with storefront JavaScript for the setup procedure. Read the Storefront JavaScript events guide for complete event details.

Use this pattern to replace a script that clicks Share and reads or removes the Share modal:

function requestSignCustomiserShareLink(callback) {
  var requestId =
    "cart-" + Date.now() + "-" + Math.random().toString(36).slice(2);
  var timeout = window.setTimeout(function () {
    cleanup();
    callback(null);
  }, 10000);  function cleanup() {
    document.removeEventListener(
      "signCustomiserShareLinkCreated",
      handleCreated,
    );
    document.removeEventListener(
      "signCustomiserShareLinkFailed",
      handleFailed,
    );
    window.clearTimeout(timeout);
  }  function handleCreated(event) {
    if (!event.detail || event.detail.requestId !== requestId) {
      return;
    }    cleanup();
    callback(event.detail.url);
  }  function handleFailed(event) {
    if (!event.detail || event.detail.requestId !== requestId) {
      return;
    }    cleanup();
    callback(null);
  }  document.addEventListener(
    "signCustomiserShareLinkCreated",
    handleCreated,
  );
  document.addEventListener(
    "signCustomiserShareLinkFailed",
    handleFailed,
  );
  document.dispatchEvent(
    new CustomEvent("signCustomiserShareLinkRequested", {
      detail: {
        requestId: requestId,
      },
    }),
  );
}function continueCartFlow() {
  requestSignCustomiserShareLink(async function (shareLinkUrl) {
    try {
      if (shareLinkUrl) {
        await saveShareLinkForCart(shareLinkUrl);
      }
    } finally {
      await continueToCart();
    }
  });
}

Save the complete returned URL. Do not build or log token parts. Do not log the ShareLink URL. Do not send it to analytics.

If the request fails or times out, continue the cart flow without a ShareLink. Do not save an empty or partial URL.