advanced_dom_changed
interface

Requires access to the Advanced DOM Events in web pixel app extensions scope. To request access, please use the form in the Partner Dashboard. This scope is only available for apps that have a heatmap and/or session recordings. The Advanced DOM Events cannot be used on custom apps.

The advanced_dom_changed event is published when the DOM has been changed in any way, such as an element being added, removed, or modified.

Shopify Plus

This event is limited on checkout to stores on the Shopify Plus plan.

Anchor to propertiesProperties

Anchor to clientId clientId string: The client-side ID of the customer, provided by Shopify
Anchor to data data
Anchor to id id string: The ID of the customer event
Anchor to name name string: The name of the customer event.
Anchor to seq seq number: The sequence index number of the event.
Anchor to timestamp timestamp string: The timestamp of when the customer event occurred, in ISO 8601 format
Anchor to type type .AdvancedDom

PixelEventsAdvancedDomChanged

The `advanced_dom_changed` event logs an instance where the DOM has been changed in any way, such as an element being added, removed, or modified.

clientId
The client-side ID of the customer, provided by Shopify
```
string
```
data
```
PixelEventsAdvancedDomChangedData
```
id
The ID of the customer event
```
string
```
name
The name of the customer event.
```
string
```
seq
The sequence index number of the event.
```
number
```
timestamp
The timestamp of when the customer event occurred, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
```
string
```
type
```
EventType.AdvancedDom
```

export interface PixelEventsAdvancedDomChanged {
  /**
   * The client-side ID of the customer, provided by Shopify
   */
  clientId?: string;
  data?: PixelEventsAdvancedDomChangedData;
  /**
   * The ID of the customer event
   */
  id?: string;

  /**
   * The name of the customer event.
   */
  name?: string;

  /**
   * The sequence index number of the event.
   */
  seq?: number;
  /**
   * The timestamp of when the customer event occurred, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
   */
  timestamp?: string;
  type?: EventType.AdvancedDom;
}

PixelEventsAdvancedDomChangedData

addedFragments
Array of `DomFragment` added to the document. Each `DomFragment` represents a sub-tree of the document. Use the `parentSerializationId` and the `prevSiblingSerializationId` to reconstruct the document.
```
DomFragment[]
```
modifiedNodes
Array of `DomNode` that have had their attributes changed. Use the `serializationId` of each to find it and update your own representation of the document.
```
DomNode[]
```
removedNodes
Array of `DomNode` removed from the document. Use the `serializationId` of each to find it and remove it from your own representation of the document.
```
DomNode[]
```

export interface PixelEventsAdvancedDomChangedData {
  /**
   * Array of `DomFragment` added to the document. Each `DomFragment` represents
   * a sub-tree of the document. Use the `parentSerializationId` and the
   * `prevSiblingSerializationId` to reconstruct the document.
   */
  addedFragments?: DomFragment[];

  /**
   * Array of `DomNode` that have had their attributes changed. Use the
   * `serializationId` of each to find it and update your own representation of
   * the document.
   */
  modifiedNodes?: DomNode[];

  /**
   * Array of `DomNode` removed from the document. Use the `serializationId` of
   * each to find it and remove it from your own representation of the document.
   */
  removedNodes?: DomNode[];
}

DomFragment

Representation of a sub-tree of the host document.

children
Array of `DomFragment` representing children of the parent `DomFragment`.
```
DomFragment[]
```
node
The node object of the `DomFragment`.
```
DomNode
```
parentSerializationId
The serialization ID of the parent node. -1 if there are no parents.
```
number
```
prevSiblingSerializationId
The serialization ID of the previous sibling node. -1 if there are no previous siblings.
```
number
```

export interface DomFragment {
  /**
   * Array of `DomFragment` representing children of the parent `DomFragment`.
   */
  children?: DomFragment[];

  /**
   * The node object of the `DomFragment`.
   */
  node?: DomNode;

  /**
   * The serialization ID of the parent node. -1 if there are no parents.
   */
  parentSerializationId?: number;

  /**
   * The serialization ID of the previous sibling node. -1 if there are no
   * previous siblings.
   */
  prevSiblingSerializationId?: number;
}

DomNode

Representation of a node in the document.

attributes
A dictionary of attributes of an element. Only available on element nodes.
```
{ [key: string]: string; }
```
checked
The checked state of an element. Only available on input element nodes.
```
boolean
```
clientRect
The coordinates of the element in the viewport. Only available on element nodes.
```
ClientRect
```
nodeType
The type of node based on the native DOM API's [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType) values. It distinguishes different kind of nodes from each other, such as elements, text and comments.
```
number
```
scroll
The scroll coordinates of the element in the viewport. Only available on element nodes.
```
ClientRect
```
serializationId
The serialization id of the node. This is a unique identifier for the node based on its stable reference in the host DOM tree.
```
number
```
tagName
A string representation of the tag of a node. Only available on element nodes.
```
string
```
textContent
The text content of an element. Only available on text nodes.
```
string
```

export interface DomNode {
  /**
   * The type of node based on the native DOM API's
   * [`nodeType`](https://developer.mozilla.org/en-US/docs/Web/API/Node/nodeType) values. It distinguishes different kind of
   * nodes from each other, such as elements, text and comments.
   */
  nodeType?: number;

  /**
   * The serialization id of the node. This is a unique identifier for the node
   * based on its stable reference in the host DOM tree.
   */
  serializationId?: number;

  /**
   * A dictionary of attributes of an element. Only available on element nodes.
   */
  attributes?: {[key: string]: string};

  /**
   * The checked state of an element. Only available on input element nodes.
   */
  checked?: boolean;

  /**
   * The coordinates of the element in the viewport. Only available on element
   * nodes.
   */
  clientRect?: ClientRect;

  /**
   * The scroll coordinates of the element in the viewport. Only available on
   * element nodes.
   */
  scroll?: ClientRect;

  /**
   * A string representation of the tag of a node. Only available on element
   * nodes.
   */
  tagName?: string;

  /**
   * The text content of an element. Only available on text nodes.
   */
  textContent?: string;
}

ClientRect

An object that contains data about an element coordinates in a viewport.

height
```
number
```
width
```
number
```
x
```
number
```
y
```
number
```

export interface ClientRect {
  height?: number;
  width?: number;
  x?: number;
  y?: number;
}

EventType

AdvancedDom
```
advanced-dom
```
Custom
```
custom
```
Dom
```
dom
```
Meta
```
meta
```
Standard
```
standard
```

export enum EventType {
  AdvancedDom = 'advanced-dom',
  Custom = 'custom',
  Dom = 'dom',
  Meta = 'meta',
  Standard = 'standard',
}

Was this section helpful?

Accessing Advanced DOM Events

App Pixel

import {register} from '@shopify/web-pixels-extension';

const domFragmentMap = new Map();

let root;

// Get the root node when it becomes available.

analytics.subscribe('advanced_dom_available', (event) => {

root = event.data.root;

});

// Keep the domFragmentMap up to date for reference with other events.

analytics.subscribe('advanced_dom_changed', (event) => {

// Handle added fragments

event.data.addedFragments.forEach((addedFragment) => {

const parentFragment = domFragmentMap.get(

addedFragment.parentSerializationId,

);

if (parentFragment) {

// Find the correct insertion index based on prevSiblingSerializationId

// Default to end if no prev sibling found

let insertIndex = parentFragment.children.length;

if (addedFragment.prevSiblingSerializationId !== -1) {

const prevSiblingIndex = parentFragment.children.findIndex(

(childFragment) =>

childFragment.node.serializationId ===

addedFragment.prevSiblingSerializationId,

);

// Insert after the previous sibling

insertIndex = prevSiblingIndex + 1;

}

// Insert at the calculated index

parentFragment.children.splice(insertIndex, 0, addedFragment);

domFragmentMap.set(addedFragment.node.serializationId, addedFragment);

}

});

// Handle removed nodes

event.data.removedNodes.forEach((removedNode) => {

const removedFragment = domFragmentMap.get(removedNode.serializationId);

const parentFragment = domFragmentMap.get(

removedFragment.parentSerializationId,

);

if (parentFragment) {

parentFragment.children = parentFragment.children.filter(

(childFragment) =>

childFragment.node.serializationId !== removedNode.serializationId,

);

domFragmentMap.delete(removedNode.serializationId);

}

});

// Handle modified nodes

event.data.modifiedNodes.forEach((modifiedNode) => {

const fragment = domFragmentMap.get(modifiedNode.serializationId);

if (fragment) {

fragment.node = modifiedNode;

}

});

examples

Accessing Advanced DOM Events

App Pixel

import {register} from '@shopify/web-pixels-extension';

const domFragmentMap = new Map();

register(({analytics}) => {
  let root;

  // Get the root node when it becomes available.
  analytics.subscribe('advanced_dom_available', (event) => {
    root = event.data.root;
  });

  // Keep the domFragmentMap up to date for reference with other events.
  analytics.subscribe('advanced_dom_changed', (event) => {
    // Handle added fragments
    event.data.addedFragments.forEach((addedFragment) => {
      const parentFragment = domFragmentMap.get(
        addedFragment.parentSerializationId,
      );
      if (parentFragment) {
        // Find the correct insertion index based on prevSiblingSerializationId
        // Default to end if no prev sibling found
        let insertIndex = parentFragment.children.length;
        if (addedFragment.prevSiblingSerializationId !== -1) {
          const prevSiblingIndex = parentFragment.children.findIndex(
            (childFragment) =>
              childFragment.node.serializationId ===
              addedFragment.prevSiblingSerializationId,
          );
          // Insert after the previous sibling
          insertIndex = prevSiblingIndex + 1;
        }
        // Insert at the calculated index
        parentFragment.children.splice(insertIndex, 0, addedFragment);
        domFragmentMap.set(addedFragment.node.serializationId, addedFragment);
      }
    });

    // Handle removed nodes
    event.data.removedNodes.forEach((removedNode) => {
      const removedFragment = domFragmentMap.get(removedNode.serializationId);
      const parentFragment = domFragmentMap.get(
        removedFragment.parentSerializationId,
      );
      if (parentFragment) {
        parentFragment.children = parentFragment.children.filter(
          (childFragment) =>
            childFragment.node.serializationId !== removedNode.serializationId,
        );
        domFragmentMap.delete(removedNode.serializationId);
      }
    });

    // Handle modified nodes
    event.data.modifiedNodes.forEach((modifiedNode) => {
      const fragment = domFragmentMap.get(modifiedNode.serializationId);
      if (fragment) {
        fragment.node = modifiedNode;
      }
    });
  });
});

advanced_dom_changedinterface

Anchor to propertiesProperties

PixelEventsAdvancedDomChanged

PixelEventsAdvancedDomChangedData

DomFragment

DomNode

ClientRect

EventType

examples

Accessing Advanced DOM Events

App Pixel

advanced_dom_changed
interface