Push Events

Learn how to send events to the Elevar Data Layer.

Overview

The Elevar Data Layer is a global array window.ElevarDataLayer that collects events generated by user activity on your website.

INFO

All sections in this guide apply to both Headless and Agnostic implementations. Follow the complete guide first, then refer to the next steps for your implementation path at the end.

Add Initialization Code

Before pushing any events, you must ensure the Elevar Data Layer is initialized. This code must run before any window.ElevarDataLayer.push() calls occur.

If the Data Layer is not initialized first, event pushes will fail. This ensures the array exists before any events are pushed, preventing errors if events fire before the Elevar script loads.

javascript

window.ElevarDataLayer ??= [];

Route Changes

Single-page applications handle navigation client-side without full page reloads. When route changes occur, Elevar’s context data such as page title, URL, and referrer can become stale. Call ElevarInvalidateContext() to refresh the context on route changes.

javascript

window.ElevarInvalidateContext?.();

This forces Elevar to refresh page context before the next event is processed.

Traditional multi-page applications that reload the page on navigation do not require this step, as context refreshes automatically on each page load.

TIP

Read this guide to learn more about the Refresh UTMs, Cookies, and Click IDs known to Elevar.

Data Layer Events

Once the Data Layer is initialized, you can begin tracking user interactions. This section covers the key events you should implement and how to push them to the Elevar Data Layer.

All events use the same structure for both Headless and Agnostic implementations.

How to Push Events:

Push events to the Data Layer using the standard array push() method:

javascript

window.ElevarDataLayer.push({
  event: "dl_event_name"
  // see examples below for additional properties
});

Each event object must include an event property that identifies the event type. Additional properties vary by event type and are shown in the examples below.

Top Funnel Events:

Top funnel events track user interactions that occur before checkout.

Event	Description
`dl_user_data`	Base event, should fire first on every page
`dl_view_item_list`	User views a collection or category page
`dl_view_search_results`	User views search results page
`dl_select_item`	User clicks a product from a collection or search page
`dl_view_item`	User views a product detail page
`dl_add_to_cart`	User adds a product to cart
`dl_remove_from_cart`	User removes a product from cart
`dl_view_cart`	User views cart or mini cart
`dl_subscribe`	User subscribes to email or SMS
`dl_sign_up`	User creates an account
`dl_login`	User logs into an account
`dl_add_to_wishlist`	User adds a product to their wishlist
`dl_customize_item`	User customizes a product
`dl_complete_quiz`	User completes a quiz
`dl_start_trial`	User starts a trial
`dl_find_location`	User searches for a store location
`dl_schedule`	User schedules or reserves something

Event Examples

This section provides detailed examples for each event type. Examples reference objects and arrays such as products, impressions, and userProperties.

Use these examples as implementation references. The complete object structures are documented in the Data Examples section below.

User Data

Fire on every page load before other events:

javascript

window.ElevarDataLayer.push({
  event: "dl_user_data",
  cart_total: "100.00",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    cart_contents: {
      products: products
    }
  }
});

Important notes:

This event is equivalent to a pageview and must fire only once per page load.
For virtual page changes (SPA navigations), this event should also fire and must be preceded by a context refresh.

View Item List

Fire when a user views a collection or category page:

javascript

window.ElevarDataLayer.push({
  event: "dl_view_item_list",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    impressions: impressions
  }
});

Important notes:

The impressions array must remain under 4000 characters. To stay within this limit, batch products across multiple events rather than sending all visible products in one event.
Trigger this event multiple times per page as needed, once for initial page load and again when users scroll and new products become visible.

View Search Results

Fire when a user views a search results page:

javascript

window.ElevarDataLayer.push({
  event: "dl_view_search_results",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    actionField: {
      list: "search results"
    },
    impressions: impressions
  }
});

Important notes:

The impressions array must remain under 4000 characters. To stay within this limit, batch products across multiple events rather than sending all visible products in one event.
Trigger this event multiple times per page as needed, once for initial page load and again when users scroll and new products become visible.

Select Item

Fire when a user clicks a product from a collection or search results:

javascript

window.ElevarDataLayer.push({
  event: "dl_select_item",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    click: {
      actionField: {
        list: location.pathname, // this should be the collection page path
        action: "click"
      },
      products: products
    }
  }
});

View Item

Fire when a user views a product detail page:

javascript

window.ElevarDataLayer.push({
  event: "dl_view_item",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    detail: {
      actionField: {
        list: location.pathname, // this should be the collection page path that user clicked product from
        action: "detail"
      },
      products: products
    }
  }
});

Important notes:

The products array should contain a single product only in this event.
For bundle products you have two options: either pass the bundle ID in the products array and trigger this event once, or trigger multiple events with individual products from the bundle. Choose the approach that best fits your reporting needs.
When users select different variants (color, size, etc.), trigger a new dl_view_item event with the updated product information, even if the page doesn't reload.
If variant selection redirects to a new page path and removes query parameters, preserve UTM parameters and click IDs in the URL to avoid losing attribution data.

Add to Cart

Fire when a user adds an item to their cart:

javascript

window.ElevarDataLayer.push({
  event: "dl_add_to_cart",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    add: {
      actionField: {
        list: location.pathname // this should be the collection page path that user clicked product from
      },
      products: products
    }
  }
});

Important notes:

Fire this event for all add to cart actions across your site, including PDPs, quick add features, and cart-side quantity increments.
When users increment product quantity in the cart, trigger this event again with the quantity field representing only the incremental amount added, not the total item count in the cart.

Remove from Cart

Fire when a user removes an item from their cart:

javascript

window.ElevarDataLayer.push({
  event: "dl_remove_from_cart",
  user_properties: userProperties,
  ecommerce: {
    currencyCode: "USD",
    remove: {
      actionField: {
        list: location.pathname // this should be the collection page path that user clicked product from
      },
      products: products
    }
  }
});

Important notes:

Fire this event for all cart removal actions, including complete product removals and quantity decrements.
When users decrement product quantity in the cart, trigger this event with the quantity field representing only the decremental amount removed, not the total item count in the cart.

View Cart

Fire when a user views the cart page or opens the cart drawer:

javascript

window.ElevarDataLayer.push({
  event: "dl_view_cart",
  user_properties: userProperties,
  cart_total: "100.00",
  ecommerce: {
    currencyCode: "USD",
    actionField: {},
    impressions: impressions
  }
});

Fire when a user subscribes to newsletter popup/form:

javascript

window.ElevarDataLayer.push({
  event: "dl_subscribe",
  lead_type: "email", // should be "email" or "phone"
  user_properties: {
    customer_email: "user@example.com", // required if lead_type is "email"
    customer_phone: "+1234567890" // required if lead_type is "phone"
  }
});

Important notes:

If the submission is for both email and phone number, call this event twice: once with lead_type: "email" and once with lead_type: "phone".
Our script automatically handles newsletter signups for certain providers (currently Klaviyo, Postscript, and Attentive), but we cannot guarantee it will work automatically. Perform the newsletter signup action on your site, then check if window.ElevarDataLayer contains an item with event: "dl_subscribe" to verify.
The dl_subscribe event is crucial for session enrichment, this is how Elevar recognizes returning users and enriches your data with the maximum amount of user identifiers. Read this article to understand how this event is important for optimizing marketing flows.

Fire when a user creates a new account:

javascript

window.ElevarDataLayer.push({
  event: "dl_sign_up",
  user_properties: userProperties
});

Important notes:

If your users don't typically sign up for accounts, this event is not required

Fire when a user logs into their account:

javascript

window.ElevarDataLayer.push({
  event: "dl_login",
  user_properties: userProperties
});

Important notes:

If your users don't typically log in to accounts, this event is not required
Fire this event after successful authentication

Add to Wishlist

Fire when a user adds a product to their wishlist:

javascript

window.ElevarDataLayer.push({
  event: "dl_add_to_wishlist",
  event_properties: {
    currency_code: "USD",
    products: products
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo, Pinterest, Snapchat.

Customize Item

Fire when a user customizes a product:

javascript

window.ElevarDataLayer.push({
  event: "dl_customize_item",
  event_properties: {
    currency_code: "USD",
    products: products
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo.

Complete Quiz

Fire when a user completes a quiz:

javascript

window.ElevarDataLayer.push({
  event: "dl_complete_quiz",
  event_properties: {
    quiz_result: "result"
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo, Google Ads, Microsoft Advertising (Bing).

Start Trial

Fire when a user starts a trial:

javascript

window.ElevarDataLayer.push({
  event: "dl_start_trial",
  event_properties: {
    pltv: "250",
    value: "50.25",
    currency_code: "USD"
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo, Google Ads, Microsoft Advertising (Bing), Snapchat.

Find Location

Fire when a user searches for a store location:

javascript

window.ElevarDataLayer.push({
  event: "dl_find_location",
  event_properties: {
    store_location: "0028342009523"
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo, Google Ads, Microsoft Advertising (Bing).

Schedule

Fire when a user schedules or reserves something:

javascript

window.ElevarDataLayer.push({
  event: "dl_schedule",
  event_properties: {
    value: "50.25",
    currency_code: "USD"
  }
});

Important notes:

This event is supported server-side by Meta (Facebook), GA4, TikTok, Klaviyo, Google Ads, Microsoft Advertising (Bing), Snapchat.

Data Examples

This section contains the full structure for objects and arrays referenced in the event examples. Use these templates when implementing events in your application by copying the structure and replacing values with your actual product and customer data.

Products Array

javascript

const products = [
  {
    id: "LB00161-34689553170476", // SKU
    name: "Lovebox Original Color & Photo", // Product title
    brand: "Lovebox INC",
    category: "Home,Living,Art & Objects,Tabletop",
    variant: "USA wall plug",
    price: "119.99",
    quantity: "1", // Not required for dl_select_item & dl_view_item
    position: item.position, // Only required for dl_select_item; position in the list indexed starting at 1
    list: "/collections/shoes", // The list the product was discovered from
    product_id: "6979886940352", // The product_id
    variant_id: "41141193965760", // id or variant_id
    compare_at_price: "139.99", // If available on dl_view_item & dl_add_to_cart otherwise use "0.0"
    image: "https://cdn.shopify.com/small.png", // If available, otherwise use an empty string
    url: "https://domain.com/products/womens-shoe?variant=123" // URL for the Product Page. Only required for dl_add_to_cart.
  }
  // ... additional products
];

Important notes:

The list property contains the collection path (e.g., /collections/shoes/) the user came from before taking a particular action on a product page. For example, if a dl_add_to_cart event is pushed, you need to persist the collection path (page URL) the user was on prior to clicking into the product page and taking that action. If the user hasn't seen a collection page at the time of the event, this property can be an empty string.

Impressions Array

javascript

// The impressions array must be less than 4000 characters.
// The most logical way to limit this is by the number of products you send
const impressions = [
  {
    id: "LB00161-34689553170476", // SKU
    name: "Lovebox Original Color & Photo", // Product title
    brand: "Lovebox INC",
    category: "Home,Living,Art & Objects,Tabletop",
    variant: "USA wall plug",
    price: "119.99",
    quantity: "1", // Only required for dl_view_cart
    list: "/collections/shoes", // Not required for dl_view_cart; The list the product is displayed in
    product_id: "6979886940352", // The product_id
    variant_id: "41141193965760", // id or variant_id
    compare_at_price: "139.99", // If available
    position: item.position // Position in the list indexed starting at 1
  }
  // ... additional products
];

Important notes:

The list property contains the collection path (e.g., /collections/shoes/) the user came from before taking a particular action on a product page. For example, if a dl_add_to_cart event is pushed, you need to persist the collection path (page URL) the user was on prior to clicking into the product page and taking that action. If the user hasn't seen a collection page at the time of the event, this property can be an empty string.

User Properties Object

javascript

const userProperties = {
  // The following fields aren't required if unavailable
  customer_address_1: "1 Hills Plantation Drive",
  customer_address_2: "",
  customer_city: "Charleston",
  customer_country: "United States",
  customer_email: "bill@gmail.com",
  customer_first_name: "Bill",
  customer_id: "5928549548188",
  customer_last_name: "Call",
  customer_order_count: "1",
  customer_phone: "999-999-9999",
  customer_province: "South Carolina",
  customer_province_code: "SC",
  customer_tags: "",
  customer_total_spent: "0.0",
  customer_zip: "22222",

  // The following field is required
  visitor_type: "logged_in" // "logged_in" || "guest"
};

Important notes:

The majority of this information can only be retrieved for a logged in user.

Headless Next Steps

Only for Shopify Headless integrations

When using checkout hosted on Shopify you only need to implement the top funnel events described above. The Shopify Source will automatically handle checkout events when the custom pixel is connected to your website.

If you're using Shopify Hydrogen, consider exploring the useAnalytics feature, a hook you can use to subscribe to analytics events. This can simplify event tracking in your Hydrogen application.

Agnostic Next Steps

Only for non-Shopify integrations

After implementing the top funnel events above, since you have control over your checkout pages and need to send checkout events manually, continue to the Checkout Events guide to complete your checkout flow tracking. This guide covers the checkout funnel events:

dl_begin_checkout: User begins checkout process
dl_add_shipping_info: User provides shipping information
dl_add_payment_info: User provides payment information
dl_purchase: User completes order

Server-to-Server Events

The Browser Setup covers browser-to-server data processing. When you push events to the Data Layer, they will be available client-side in the Data Layer, but also routed to the Elevar app to trigger server events.

You can also send server-to-server events directly from your backend for improved reliability and data accuracy. This is especially useful for critical events like dl_purchase. Learn more in the Server Setup guide for implementation details.

Push Events ​

Overview ​

Add Initialization Code ​

Route Changes ​

Data Layer Events ​

How to Push Events: ​

Top Funnel Events: ​

Event Examples ​

Data Examples ​

Headless Next Steps ​

Agnostic Next Steps ​

Server-to-Server Events ​

Push Events

Overview

Add Initialization Code

Route Changes

Data Layer Events

How to Push Events:

Top Funnel Events:

Event Examples

Data Examples

Headless Next Steps

Agnostic Next Steps

Server-to-Server Events