> For the complete documentation index, see [llms.txt](https://docs.adpage.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.adpage.io/integrations-websites/custom/add-datalayer-events.md).

# Add dataLayer events

Learn how to setup custom datalayer events

### 1. build the dataLayer events

AdPage follows the Google Tag Manager dataLayer standard. Learn more about event structure in the [Google documentation](https://support.google.com/analytics/answer/9267735?hl=en).

The following events are important for an eCommerce website:

* user\_data (installed in step 2.1)
* view\_item\_list ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#view_item_list))
* view\_item ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#view_item))
* add\_to\_cart ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#add_to_cart))
* remove\_from\_cart ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#remove_from_cart))
* view\_cart ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#view_cart))
* begin\_checkout ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#begin_checkout))
* add\_payment\_info ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#add_payment_info))
* add\_shipping\_info ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#add_shipping_info))
* purchase ([Google documentation](https://developers.google.com/analytics/devguides/collection/ga4/reference/events?client_type=gtm#purchase))

> **Note:** These events are a guide for eCommerce websites. Custom events or other website goals, such as lead generation, may require different events.

Prefix events with `trytagging_` to avoid conflicts with existing dataLayer events.

### 2. Add the user\_data datalayer event

The `user_data` event is the first event sent on your website. Add it before other dataLayer events. It acts as the Google Tag Manager start signal. Tracking data may not arrive correctly without it.

{% hint style="info" %}
When using webhooks, each page must override `client_id`, `session_id`, and `session_count` with Google-generated IDs. Trigger the Google tag from the dataLayer `user_data` event. Trigger every other event only after the Google tag.
{% endhint %}

The `user_data` event requires an additional script. Add this script to the `<body>`:

```xml
<script  defer  src="https://[connected_domain_name]/user-data-minified.js">
</script>
```

{% hint style="info" %}
**Note:** Find the connected domain in the installation link. You can also find it under **Implementation** → **Domain name** in the AdPage Tagging dashboard. Update the URL for each domain.
{% endhint %}

This script provides two JavaScript helper functions:

```javascript
window.taggingHelpers.getMarketingObject(); // Marketing object

window.taggingHelpers.getDeviceInfo(); // Device object
```

Then send the first `user_data` event in JavaScript:

```javascript
// Run this code only after window.taggingHelpers is available.
// It loads through a defer tag, so it does not block the website.

window.dataLayer.push({

  event: "trytagging_user_data",

  marketing: window.taggingHelpers.getMarketingObject(),

  device: window.taggingHelpers.getDeviceInfo(),

});
```

Add `marketing` to every subsequent event. This is an example `view_item` event:

```php
window.dataLayer.push({

  event: "trytagging_view_item",

  ecommerce: {

    currency: "EUR",

    value: 100,

    items: [

      {

        item_id: "123456",

        item_name: "Product Name",

        price: 100,

        item_category: "Product Category",

      },

    ],

  },

  marketing: window.taggingHelpers.getMarketingObject(),

});
```

#### 2.1 Optional wait for the user\_data script

We recommend loading the `user_data` script with `defer`. This prioritizes other critical page elements. It also means the script may not be immediately available.

The `user_data` script sends a custom JavaScript event when its functionality becomes available. Use that event as follows:

```javascript
document.addEventListener("trytagging_user_data_ready", (event) => {
  const marketingData = window.taggingHelpers.getMarketingObject();

  console.log("Marketing Data:", marketingData);
});
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.adpage.io/integrations-websites/custom/add-datalayer-events.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.