---
url: /guides/api/browser-setup/push-events.md
---
# 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](/guides/api/additional-resources/refreshing-context) 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.

::: details 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.

:::

::: details 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.

:::

::: details 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.

:::

::: details 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
    }
  }
});
```

:::

::: details 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.

:::

::: details 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.

:::

::: details 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.

:::

::: details 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
  }
});
```

:::

::: details Subscribe

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](https://docs.getelevar.com/docs/understanding-the-dl_subscribe-event)
  to understand how this event is important for optimizing marketing flows.

:::

::: details Sign Up

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

:::

::: details Login

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

:::

::: details 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.

:::

::: details 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.

:::

::: details 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).

:::

::: details 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.

:::

::: details 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).

:::

::: details 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.

::: details 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.

:::

::: details 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.

:::

::: details 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](/guides/api/headless/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](https://shopify.dev/docs/api/hydrogen/2024-07/hooks/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](/guides/api/agnostic/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](/guides/api/agnostic/server-setup) guide for implementation
details.
