Codify your headless Shopify store

Who Should Follow This Guide:

This guide is intended for developers and technical teams managing headless Shopify stores who want to implement accurate event tracking using Blotout. If your Shopify store uses a custom frontend (headless) or custom checkout, you must follow these instructions to ensure proper event tracking.

Why Event Codification is Required

When a Shopify store is headless, the Blotout Shopify App cannot automatically track events from the website. Shopify’s standard web pixel and app-based tracking only work with traditional (non-headless) stores. Result: Custom event codification is required to ensure accurate tracking of user interactions and conversions.

Event Codification Requirements

The events you need to implement depend on whether your storefront or checkout is headless.

Case 1: Headless Storefront with Shopify Checkout

If your pre-checkout experience is headless (custom frontend) and the checkout is hosted by Shopify, you must codify the following events on your website:

Event Name	Trigger
PageView	Fired on every page load
ViewContent	Fired on product detail pages with product payload
AddToCart	Fired when a product is added to the cart
CompleteRegistration	Fired when a user completes account registration | optional event
Lead	Fires on submission of the footer or pop-up subscribe form

Note: These events must be triggered from your headless frontend and sent to Blotout with the appropriate payload.

Case 2: Fully Headless Checkout (Custom Checkout)

If both your storefront and checkout are headless, you must additionally codify checkout and purchase-related events.

Event Name	Trigger
InitiateCheckout	Fired when the user lands on the checkout page
AddShippingInfo	Fired when shipping details are submitted
AddPaymentInfo	Fired when payment details are submitted
Purchase	Fired once the purchase is successfully completed

SDK Initialization and Event Dispatching

Before sending any events or user data, you must initialize the Edgetag SDK.

Once initialized, use the tag method to:

• Send event (e.g., PageView, AddToCart, Purchase)

Use data/user method to:

• Send user information and attributes

Basic Flow

1. Initialize the Edgetag SDK

2. Call the tag method to send events

3. Send user data or PII separately using data/user methods

Sending User Information

All user information must be sent using the methods below only.

To send user information, please follow the relevant integration guide based on your implementation method:

1. Native JavaScript

2. NPM Package

3. HTTP API

Important: Always send the standard keys with the proper type; otherwise, the events will fail validation.

Methods for Event Codification

There are multiple supported methods to implement event tracking:

1. Native JavaScript

   • Directly trigger events using custom JavaScript in your frontend.

2. NPM Packages

   • Use our official or supported NPM packages to simplify integration.

3. HTTP API Calls

   • Send events directly to our ingestion endpoint from your backend or frontend (recommended server-side).

4. Webhooks

Event Payload Requirements

Each event must include the required payload, such as:

• Product or cart data

• Order values and currency

• Event-specific metadata

Please follow the standard event payload specification outlined in our official integration guide to ensure proper processing and activation.