Track iAdvize events in your Analytics tool

Overview

When integrating iAdvize on your website, you may want to measure and analyse visitor engagement, conversation activity, and AI Shopping Assistant interactions within your existing analytics stack. Whether you use Google Analytics 4, Adobe Analytics, or Piano Analytics, the recommended approach is to push iAdvize events into the dataLayer and route them through your tag management system (e.g. Google Tag Manager).The iAdvize Web SDK exposes a set of lifecycle events covering the full visitor journey:

• iAdvize tag initialization

• Cookie and GDPR consent status

• Engagement rule triggers

• Widget impressions and clicks

• Shopping Panel state changes

• Conversation start and end

• Add-to-Cart actions from the AI Shopping Assistant

By listening to these events and forwarding them to the window.dataLayer, you gain full visibility into iAdvize engagement metrics alongside your existing analytics data, without requiring any direct integration with individual analytics platforms.

Prerequisites

• The iAdvize main tag must be deployed on your website.

• window.dataLayer must be initialized (this happens automatically if Google Tag Manager is already in place).

Note: Event names and property keys used in this guide are suggestions. Feel free to adapt them to your internal naming conventions.

General Structure

All iAdvize event listeners must be registered inside the callback passed to window.iAdvizeInterface.push. This callback executes as soon as the iAdvize main tag is fully loaded and ready.

window.dataLayer = window.dataLayer || [];
window.iAdvizeInterface = window.iAdvizeInterface || [];

window.iAdvizeInterface.push(function (iAdvize) {
  // Register all your iAdvize.on(...) listeners here
});

dataLayer Object Convention

All iAdvize-specific properties are grouped under an iAdvize key in each pushed object. This prevents naming collisions with other properties already present on your site.

window.dataLayer.push({
  event: "iAdvize...",
  iAdvize: {
    property: "value"
  }
});

In Google Tag Manager, Data Layer Variables are accessible using dot notation: iAdvize.widgetType, iAdvize.conversationId, etc.

Available Events

1. iAdvize Main Tag Loaded

When it fires: As soon as the iAdvize main tag has finished loading and initializing on the page.

window.iAdvizeInterface.push(function (iAdvize) {
  window.dataLayer.push({
    event: "iAdvizeMainTagLoaded"
  });
});

No additional properties. This event signals that the SDK is ready.

2. Visitor Consent Status

When it fires:

• get: Returns the current consent value at the time of the call. Returns null if the visitor has not yet made a choice, true if accepted, false if refused.

• on (change): Fires each time the cookie or GDPR consent value changes, typically when the visitor interacts with the consent banner, or implicitly when they start a conversation (both cookie and GDPR consents are automatically accepted upon conversation creation).

// ── Cookie Consent ──
// Status on page load
window.dataLayer.push({
  event: "iAdvizeCookiesConsentStatus",
  iAdvize: {
    cookiesConsentValue: iAdvize.get("visitor:cookiesConsent") // true, false or null
  }
});

// Changes during the session
iAdvize.on("visitor:cookiesConsentChange", function (visitorCookiesConsent) {
  window.dataLayer.push({
    event: "iAdvizeCookiesConsentUpdated",
    iAdvize: {
      cookiesConsentValue: visitorCookiesConsent // true = accepted, false = refused
    }
  });
});

// ── GDPR Consent ──
// Status on page load
window.dataLayer.push({
  event: "iAdvizeGDPRConsentStatus",
  iAdvize: {
    gdprConsentValue: iAdvize.get("visitor:GDPRConsent") // true, false or null
  }
});

// Changes during the session
iAdvize.on("visitor:GDPRConsentChange", function (visitorGDPRConsent) {
  window.dataLayer.push({
    event: "iAdvizeGDPRConsentUpdated",
    iAdvize: {
      gdprConsentValue: visitorGDPRConsent // true = accepted, false = refused
    }
  });
});

Event	GTM Key	Possible Values
iAdvizeCookiesConsentStatus	iAdvize.cookiesConsentValue	true, false, null
iAdvizeCookiesConsentUpdated	iAdvize.cookiesConsentValue	true, false
iAdvizeGDPRConsentStatus	iAdvize.gdprConsentValue	true, false, null
iAdvizeGDPRConsentUpdated	iAdvize.gdprConsentValue	true, false

3. Engagement Rule Triggered

When it fires: When an engagement rule (also called a "targeting rule") is evaluated and executed on the visitor's side. This means:

1. The visitor meets the rule conditions (URL, time spent, pages viewed, etc.)

2. The rule is not capped (display limit not reached)

3. The ruleId is emitted only once per rule per page

⚠️ Important distinction: This event fires before the widget is displayed. A rule can be "triggered" but the widget may not appear (e.g. if the required CSS selector is not found on the page).

iAdvize.on("engagementRule:triggered", function (ruleId) {
  window.dataLayer.push({
    event: "iAdvizeEngagementRuleTriggered",
    iAdvize: {
      engagementRuleId: ruleId
    }
  });
});

GTM Key	Value
iAdvize.engagementRuleId	Engagement rule ID

4. Widget Displayed

When it fires: When a widget or notification is actually rendered on the page. This occurs after:

1. The engagement rule has been triggered (engagementRule:triggered)

2. Rendering prerequisites are met (CSS selector found for embedded buttons, viewport conditions, etc.)

iAdvize.on("engagementNotification:displayed", function (notification) {
  window.dataLayer.push({
    event: "iAdvizeWidgetDisplayed",
    iAdvize: {
      widgetType: notification.type,
      widgetId: notification.id,
      engagementRuleId: notification.ruleId
    }
  });
});

GTM Key	Value
iAdvize.widgetType	"BADGE", "CLASSIC", "MESSAGING", "INVITATION", "MINI_BADGE", "CHATBOX", "MESSAGE", "CUSTOM_BUTTON", "EMBEDDED_CONVERSATION_STARTER"
iAdvize.widgetId	Widget ID
iAdvize.engagementRuleId	Associated engagement rule ID

5. Widget Clicked

When it fires: When the visitor clicks on a widget or notification and the engagement is accepted.

iAdvize.on("engagementNotification:clicked", function (notification) {
  var properties = {
    widgetType: notification.type,
    widgetId: notification.id,
    engagementRuleId: notification.ruleId
  };

  // Only populated for Conversation Starters:
  // contains the text of the question the visitor clicked on
  if (notification.text) {
    properties.conversationStarterText = notification.text;
  }

  window.dataLayer.push({
    event: "iAdvizeWidgetClicked",
    iAdvize: properties
  });
});

GTM Key	Value
iAdvize.widgetType	Widget type
iAdvize.widgetId	Widget ID
iAdvize.engagementRuleId	Engagement rule ID
iAdvize.conversationStarterText	(Only for EMBEDDED_CONVERSATION_STARTER) Text of the clicked question

6. Shopping Panel State Change

When it fires:

• OPENED: When the Shopping Panel opens (click on notification, programmatic opening, conversation resumption)

• REDUCED: When the visitor minimizes the panel

• CLOSED: When the visitor fully closes the panel

iAdvize.on("chatbox:statusChange", function (status) {
  window.dataLayer.push({
    event: "iAdvizeShoppingPanelStatusChanged",
    iAdvize: {
      shoppingPanelStatus: status // "OPENED", "REDUCED" or "CLOSED"
    }
  });
});

GTM Key	Value
iAdvize.shoppingPanelStatus	"OPENED", "REDUCED" or "CLOSED"

7. Conversation Started / Ended

When it fires:

• Start (conversationId changes from null to non-null): When a chat conversation is effectively created server-side. This occurs after the visitor clicks the widget and sends the initial message.

• End (conversationId changes from non-null to null): When the conversation is closed by the agent or the AI Shopping Assistant.

iAdvize.on("conversation:idChange", function (conversationId, previousConversationId) {
  window.dataLayer.push({
    event: conversationId ? "iAdvizeConversationStarted" : "iAdvizeConversationEnded",
    iAdvize: {
      conversationId: conversationId || previousConversationId
    }
  });
});

Case	event	iAdvize.conversationId
Start	"iAdvizeConversationStarted"	New conversation ID
End	"iAdvizeConversationEnded"	Ended conversation ID

8. Add to Cart Click (AI Shopping Assistant)

When it fires: When the visitor clicks the "Add to Cart" button on a product card recommended by the AI Shopping Assistant within the conversation.

⚠️ Prerequisite: The functional addToCart:clicked callback (with resolve/reject) must already be implemented in your site's native code for the Add to Cart button to appear in the conversation. Do not implement this analytics listener independently without the functional callback already in place, as it could activate the Add to Cart feature in iAdvize conversations before your site's cart logic is ready.

// Analytics-only listener (does not interfere with the functional callback)
iAdvize.on("addToCart:clicked", function ({ productId }) {
  window.dataLayer.push({
    event: "iAdvizeAddToCartClicked",
    iAdvize: {
      productId: productId
    }
  });
});

To also track the outcome (success or failure), add the dataLayer pushes inside the existing functional callback:

iAdvize.on("addToCart:clicked", function ({ productId, resolve, reject }) {
  addToCart(productId)
    .then(function (response) {
      if (response.success) {
        resolve(true);
        window.dataLayer.push({ event: "iAdvizeAddToCartSucceeded", iAdvize: { productId: productId } }); // ← add
      } else {
        resolve(false);
        window.dataLayer.push({ event: "iAdvizeAddToCartFailed", iAdvize: { productId: productId } }); // ← add
      }
    })
    .catch(function (error) {
      reject(error);
      window.dataLayer.push({ event: "iAdvizeAddToCartFailed", iAdvize: { productId: productId } }); // ← add
    });
});

Event	Triggered when	iAdvize.productId
"iAdvizeAddToCartClicked"	Button clicked	Product ID
"iAdvizeAddToCartSucceeded"	Cart addition succeeded	Product ID
"iAdvizeAddToCartFailed"	Cart addition failed or error	Product ID

Full Consolidated Script

Here is a complete script combining all events described in this guide. You can implement it as-is or select only the events relevant to your use case. Event names can also be renamed to match your analytics taxonomy.

window.dataLayer = window.dataLayer || [];
window.iAdvizeInterface = window.iAdvizeInterface || [];

window.iAdvizeInterface.push(function (iAdvize) {

  // ── 1. iAdvize main tag loaded ──
  window.dataLayer.push({
    event: "iAdvizeMainTagLoaded"
  });

  // ── 2a. Cookie consent - status on load ──
  window.dataLayer.push({
    event: "iAdvizeCookiesConsentStatus",
    iAdvize: {
      cookiesConsentValue: iAdvize.get("visitor:cookiesConsent")
    }
  });

  // ── 2b. Cookie consent - changes ──
  iAdvize.on("visitor:cookiesConsentChange", function (visitorCookiesConsent) {
    window.dataLayer.push({
      event: "iAdvizeCookiesConsentUpdated",
      iAdvize: {
        cookiesConsentValue: visitorCookiesConsent
      }
    });
  });

  // ── 2c. GDPR consent - status on load ──
  window.dataLayer.push({
    event: "iAdvizeGDPRConsentStatus",
    iAdvize: {
      gdprConsentValue: iAdvize.get("visitor:GDPRConsent")
    }
  });

  // ── 2d. GDPR consent - changes ──
  iAdvize.on("visitor:GDPRConsentChange", function (visitorGDPRConsent) {
    window.dataLayer.push({
      event: "iAdvizeGDPRConsentUpdated",
      iAdvize: {
        gdprConsentValue: visitorGDPRConsent
      }
    });
  });

  // ── 3. Engagement rule triggered ──
  iAdvize.on("engagementRule:triggered", function (ruleId) {
    window.dataLayer.push({
      event: "iAdvizeEngagementRuleTriggered",
      iAdvize: {
        engagementRuleId: ruleId
      }
    });
  });

  // ── 4. Widget displayed ──
  iAdvize.on("engagementNotification:displayed", function (notification) {
    window.dataLayer.push({
      event: "iAdvizeWidgetDisplayed",
      iAdvize: {
        widgetType: notification.type,
        widgetId: notification.id,
        engagementRuleId: notification.ruleId
      }
    });
  });

  // ── 5. Widget clicked ──
  iAdvize.on("engagementNotification:clicked", function (notification) {
    var properties = {
      widgetType: notification.type,
      widgetId: notification.id,
      engagementRuleId: notification.ruleId
    };
    if (notification.text) {
      properties.conversationStarterText = notification.text;
    }
    window.dataLayer.push({
      event: "iAdvizeWidgetClicked",
      iAdvize: properties
    });
  });

  // ── 6. Shopping Panel state change ──
  iAdvize.on("chatbox:statusChange", function (status) {
    window.dataLayer.push({
      event: "iAdvizeShoppingPanelStatusChanged",
      iAdvize: {
        shoppingPanelStatus: status
      }
    });
  });

  // ── 7. Conversation started / ended ──
  iAdvize.on("conversation:idChange", function (conversationId, previousConversationId) {
    window.dataLayer.push({
      event: conversationId ? "iAdvizeConversationStarted" : "iAdvizeConversationEnded",
      iAdvize: {
        conversationId: conversationId || previousConversationId
      }
    });
  });

  // ── 8. Add to Cart - click tracking ──
  // The SDK supports multiple listeners on addToCart:clicked.
  // This listener runs without interfering with the site's functional callback.
  iAdvize.on("addToCart:clicked", function ({ productId }) {
    window.dataLayer.push({
      event: "iAdvizeAddToCartClicked",
      iAdvize: {
        productId: productId
      }
    });
  });

});

Connecting to Your Analytics Tool via GTM

Step 1 - Deploy the Tracking Script

Create a Custom HTML tag in GTM with the full script above. Use an Initialization trigger to fire it as early as possible in the page lifecycle.

⚠️ The iAdvizeAddToCartSucceeded and iAdvizeAddToCartFailed events require integration within the site's native source code, inside the existing functional addToCart:clicked callback.

Step 2 - Create GTM Data Layer Variables

In GTM, create Data Layer Variable variables using dot notation to access iAdvize properties:

GTM Variable Name	dataLayer Path
iAdvize - Cookies Consent Value	iAdvize.cookiesConsentValue
iAdvize - GDPR Consent Value	iAdvize.gdprConsentValue
iAdvize - Engagement Rule ID	iAdvize.engagementRuleId
iAdvize - Widget Type	iAdvize.widgetType
iAdvize - Widget ID	iAdvize.widgetId
iAdvize - Conversation Starter Text	iAdvize.conversationStarterText
iAdvize - Shopping Panel Status	iAdvize.shoppingPanelStatus
iAdvize - Conversation ID	iAdvize.conversationId
iAdvize - Product ID	iAdvize.productId

Step 3 - Create GTM Triggers

Create one Custom Event trigger per event you want to forward to your analytics tool. Then configure your analytics tags (GA4, Piano Analytics, Adobe Analytics, etc.) to fire on these triggers, using the Data Layer Variables defined above as event parameters.

dataLayer Event	Suggested Analytics Use Case
iAdvizeMainTagLoaded	Initialization / debug
iAdvizeCookiesConsentStatus	Cookie consent audit on load
iAdvizeCookiesConsentUpdated	Cookie consent change tracking
iAdvizeGDPRConsentStatus	GDPR consent audit on load
iAdvizeGDPRConsentUpdated	GDPR consent change tracking
iAdvizeEngagementRuleTriggered	Active engagement rule measurement
iAdvizeWidgetDisplayed	Widget impression
iAdvizeWidgetClicked	Widget click / Conversation Starter interaction
iAdvizeShoppingPanelStatusChanged	Panel open / minimize / close
iAdvizeConversationStarted	Conversation start
iAdvizeConversationEnded	Conversation end
iAdvizeAddToCartClicked	Add to Cart click
iAdvizeAddToCartSucceeded	Successful cart addition
iAdvizeAddToCartFailed	Failed cart addition

End-to-End Example

This section walks through a complete, concrete example of sending the iAdvizeConversationStarted event to Google Analytics 4 via Google Tag Manager. The same logic applies to any other event in this guide.

What we want to achieve

When a visitor starts a conversation with iAdvize, send a GA4 event named iadvize_conversation_started with the conversation ID as a custom parameter.

Step 1 - Push the event to the dataLayer

The following listener (already part of the consolidated script above) pushes the event when a conversation begins:

iAdvize.on("conversation:idChange", function (conversationId, previousConversationId) {
  if (conversationId) {
    window.dataLayer.push({
      event: "iAdvizeConversationStarted",
      iAdvize: {
        conversationId: conversationId
      }
    });
  }
});

Step 2 - Create a Data Layer Variable in GTM

In GTM, go to Variables > User-Defined Variables > New and create a Data Layer Variable:

Field	Value
Variable Name	iAdvize - Conversation ID
Data Layer Variable Name	iAdvize.conversationId
Data Layer Version	Version 2

Step 3 - Create a Custom Event Trigger in GTM

Go to Triggers > New and create a Custom Event trigger:

Field	Value
Trigger Name	iAdvize - Conversation Started
Event Name	iAdvizeConversationStarted
Fire on	All Custom Events

Step 4 - Create a GA4 Event Tag in GTM

Go to Tags > New and create a Google Analytics: GA4 Event tag:

Field	Value
Tag Name	GA4 - iAdvize Conversation Started
Measurement ID	Your GA4 Measurement ID (e.g. G-XXXXXXXXXX)
Event Name	iadvize_conversation_started
Event Parameters
Parameter Name	conversation_id
Parameter Value	{{iAdvize - Conversation ID}} (the variable created in Step 2)
Triggering	iAdvize - Conversation Started (the trigger created in Step 3)

Step 5 - Verify in GA4 DebugView

1. Enable Preview mode in GTM and open your website.

2. Trigger a conversation with iAdvize.

3. In GTM Preview, confirm the tag GA4 - iAdvize Conversation Started fired on the iAdvizeConversationStarted event.

4. In GA4, open Admin > DebugView and verify the iadvize_conversation_started event appears with the conversation_id parameter populated.

Once validated, submit and publish your GTM container.

💡 Reusable pattern: This exact same flow applies to any other iAdvize event. Simply swap the trigger (iAdvizeWidgetDisplayed, iAdvizeWidgetClicked, etc.) and define the relevant event parameters using the corresponding Data Layer Variables.