🚧
Public preview
This feature is currently in preview and may be subject to short notice changes or improvements. If you're interested in joining the preview, contact your Customer Success representative.

Using the Dotdigital Tag, you can capture events such as page views, user logins, product browsing and cart updates, and access this data in your Dotdigital Marketing and Personalization accounts.

These methods facilitate real-time data ingestion, supporting personalized marketing and analytics by mapping data to defined schemas.

They are called in JavaScript to track user actions and send data to a server endpoint.

Key events

Event type	Method	Description
Set configuration	`window.ddg.configuration(data)`	Sets site brand, language, and currency. Can optionally pass an existing session ID to Personalization. Also sets cartDelay and programID for Dotdigital Marketing abandoned cart enrolments.
Page change	`window.ddg.track(data)`	Tracks page visits. Certain page types have more specific calls which are preferred. Learn more in the section Page-specific calls.
User identification	`window.ddg.identify({...})`	Identifies a user with specific attributes such as email, mobile number, and name.
Product browse	`window.ddg.productBrowse({...} )`	Tracks product browsing events with detailed product information.
Product list	`window.ddg.productList({data})`	Tracks a list of products viewed by the contact.
Cart update	`window.ddg.cartUpdate({...})`	Updates cart information with detailed cart and product data.
Checkout	`window.ddg.checkout({...})`	Tracks checkout events. When used, the cart Insight data’s CartPhase in Dotdigital Marketing is set to `ORDER_CHECKOUT` .
Purchase complete	`window.ddg.purchaseComplete({...})`	Tracks purchase completion events. When used, the cart Insight data’s CartPhase in Dotdigital Marketing is set to `ORDER_COMPLETE` .
Custom event	`window.ddg.event("eventName",{...})`	Sends custom events defined by you.*

*Custom events are only available in the Dotdigital Marketing CXDP account package.

Method reference

ddg.configuration(data)

Sets siteBrand, and language and currency for the session. Can also be used to pass a session ID of your choosing to Dotdigital Personalization, for example, from your website backend or a server-side integration. Also sets cartDelay and programID for Dotdigital Marketing abandoned cart enrolments, if required.

You can either call the method once at the beginning of a browsing session, then only call it again if any of the details change, or you can call the method on every page load, as you prefer.

Name	Type	Description	Required
marketing>cartDelay	number	Number in minutes after a cart abandonment that user’s are enrolled in the abandoned cart program.	No
marketing>programID	string	ID of the abandoned cart program in Dotdigital Marketing.	No
personalization>siteBrand	string	The Personalization siteBrand for the session.	Yes
personalization>sessionID	string	Existing ID for the session passed from another system or site backend.	No
site>language	string	The site language for the user.	Yes*
site>currency	string	The site currency.	Yes*

*These values must be consistent with other values in the product collection to avoid creating duplicate product records.

Personalization session ID

sessionID allows you to pass in your own session identifier from your site backend, another system, or a server-side integration and have the Personalization SDK reference that identifier when passing activity into Dotdigital Personalization.

When provided, sessionID is automatically included on each subsequent call for the session. sessionID is passed in addition to standard Dotdigital system identifiers used by the SDK. If no value is passed for sessionID then the SDK manages it's own session ID.

You should set sessionID as early as possible so that the as much activity as possible can be attributed to it, but the value can b set at whatever point in the session it becomes available.

Example

window.ddg.configuration({
    marketing: {
        cartDelay: 30,
        programId: 12345
     },
    personalization: {        
        siteBrand: "US",
        sessionID: "session ID 123",
    },
    site: {
        language: "EN",
        currency: "USD"
    }
});

ddg.track(pageData)

Tracks page visits.

📘
Some page types have page-specific calls which should be used in place of ddg.track. Learn more.

pageData object

Name	Type	Description	Required
url	string	The full URL of the visited page.	Yes
title	string	The title of the visited page.	Yes
localTime	date \| string	The local time of the page visit in either the ISO8601 string or `date` format. Defaults to now if not provided.	No
pageType	number*	The type of the visited webpage. Certain page types have more specific calls which should be used in place of `ddg.track`. These calls send the relevant `pageType` automatically. Learn more in the section Page-specific calls.	Yes
extraData	object	Additional data related to the session.	No

Example

window.ddg.track({
    url: "https://example.com/checkout",
    title: "Cart checkout",
    localTime: "2025-11-25T13:37:57Z",
    pageType: 5
});

📘
*pageType can be one of 12 pre-defined page types, represented by a specific integer.
Any page that doesn’t match with these pre-defined types must be classified as Other (0). If pageType is omitted or an unsupported integer is provided, the pageType is automatically classified as Other.

Page type Representative integer
Other 0
Home_Page 1
Product_Browse 2
Product_List 3
Cart 4
Checkout 5
Purchase_Complete 6
Login 7
Login_Complete 8
Register 9
Register_Complete 10
Account 11
Newsletter 12

Page type	Representative integer
Other	0
Home_Page	1
Product_Browse	2
Product_List	3
Cart	4
Checkout	5
Purchase_Complete	6
Login	7
Login_Complete	8
Register	9
Register_Complete	10
Account	11
Newsletter	12

Page-specific calls

The following calls should be used for each of the specified pages of your site, in place of ddg.track.

🚧
Do not duplicate events
If you’re using one of the below page-specific calls, you must not fire a ddg.track call on the same page.

Method	PageType set	Example
ddg.homepage(data)	`PAGE_TYPE_HOME_PAGE` (1)	Homepage visits
ddg.cart(data)	`PAGE_TYPE_CART` (4)	Cart page views
ddg.login(data)	`PAGE_TYPE_LOGIN` (7)	Login page views
ddg.loginComplete(data)	`PAGE_TYPE_LOGIN_COMPLETE` (8)	Successful logins
ddg.register(data)	`PAGE_TYPE_REGISTER` (9)	Registration page views
ddg.registerComplete(data)	`PAGE_TYPE_REGISTER_COMPLETE` (10)	Successful registrations
ddg.accountEdit(data)	`PAGE_TYPE_ACCOUNT` (11)	Account edit page views
ddg.newsletterEdit(data)	`PAGE_TYPE_NEWSLETTER` (12)	Newsletter subscription page views

Parameters

Each of the above accept an optional data object with the same fields as ddg.track(), except pageType, which is set automatically:


{
    url: string,           // Required - Page URL
    title: string,         // Required - Page title
    localTime?: Date | string,  // Optional - Local time
    extraData?: object,    // Optional - Additional data
}

ddg.identify(identityDetails)

Identifies a user with specific attributes such as email, mobile number, and name.

identityDetails object

Name	Type	Description	Required
email	string	User's email address. At least one identifier (email or mobile number) is required.	Yes If `mobileNumber` is not provided.
mobileNumber	string	User's mobile number in E.164 format. At least one identifier (email or mobile number) is required.	Yes If `email` is not provided.
firstName	string	User's first name.	No
lastName	string	User's last name.	No
fullName	string	User's full name.	No
customerId	string	Unique identifier for the customer. This value maps to the CID field in Personalization, but is not automatically mapped to a custom ID field in Marketing. The value is stored is webInsight records in Marketing.	No

Example

window.ddg.identify({
  email: "[email protected]",
  mobileNumber: "+447911123456",
  firstName: "Jane",
  lastName: "Doe",
  fullName: "Jane Doe"
});

ddg.getTrackedId()

Returns the Dotdigital Marketing Contact ID for known users, or undefined if an anonymous user.

Example

var contactId = window.ddg.getTrackedId();

ddg.productBrowse(product)

Tracks product browsing events with detailed product information.

product object

Name	Type	Description	Required
productId	string	Unique identifier for the product.	Yes
sku	string	Stock Keeping Unit.	Yes
name	string	Name of the product.	Yes
url	string	Full URL of the product page.	Yes
imageUrl	string	Full URL of the product thumbnail image.	Yes
imageThumbnailUrl	string	Full URL of the product thumbnail image.	Yes
price	number	Price of the product.	Yes
salePrice	number	Sale price of the product.	No
currency	string	Currency code in ISO 4217 format	Yes*
priceInclTax	number	Price including tax.	No
salePriceInclTax	number	Sale price including tax.	No
status	string	Status of the product.	No
stock	number	Stock of the product.	No
description	string	Description of the product.	No
categories	array[category]	Categories the product belongs to.	No, but recommended
personalization>siteBrand	string	The Dotdigital Personalization siteBrand for the product.	No siteBrand must be set in the configuration call. If siteBrand is set at the product level, this takes precedence.
language	string	Language code in ISO 639 format.	No*
variantId	string	Unique identifier of the variant.	No, but recommended
variants	array[variant]	Array of product variants.	No, but recommended
options	object	Additional product-related data specific to the customer. Persists only for the session.	No

*If lang, currency , and sbr are included in your product sync to Personalization, these details must also be passed through the Dotdigital Tag to ensure the product records can be matched.

variant object

Property name	Type	Required
id	string	Yes
url	string	Yes
name	string	Yes
stock	number	Yes
image	string	Yes
imageThumbnailUrl	string	No
price	number	No
priceInclTax	number	No
sku	string	No
currency	string	No
description	string	No
salePrice	number	No
salePriceInclTax	number	No
categories	array[category]	No
extraData	object	No
language	string	No
status	string	No
stock	number	No

category object

A product category can be either a string or { categoryName: string, groupName: string, }

Property name	Data type	Required
categoryName	string	Yes
groupName	string	Yes
replace	Boolean	No, but recommended If not provided, default is false.

Replace property behavior

replace = true
Existing data for that tag name is replaced. This is useful if you want to update incorrect data.

replace = false
Existing data for that tag name is not replaced. This allows you to append additional tag names.

Example

window.ddg.productBrowse({  
    productId: 'uniqueproductid',  
    name: 'name', 
    options: {
      “Option 1”: 5,
      “Option 2”: “Sam”
    }, 
    price: 1.12,  
    imageThumbnailUrl: 'http://www.image.com/thumbnail.jpg',  
    imageUrl: 'http://www.image.com/image.jpg',  
    priceInclTax: 1.35,  
    salePrice: 3.2,  
    salePriceInclTax: 3.5,  
    sku: 'sku-123',  
    status: 'status',  
    stock: 1,  
    url: 'http://product.com/product.html',  
    brand: 'brand name',  
    language: 'language',  
    categories: [  
        'category 1',  
        { categoryName: 'category 3', groupName: 'category group', replace: true }],  
    currency: 'currency',  
    description: 'description',  
    extraData: {  
        'string value': 'hello world',  
        'int value': 1542,  
        'float value': 1.12,  
        'boolean value': true  
    },  
		personalization: {        
        siteBrand: "US"
    },
    variantId: 'var1',  
    variants: [  
        {  
            id: 'var1',  
            image: 'http://www.image.com/image_a.jpg',  
            name: 'variation 1',
            stock: 1,
            url: 'http://product.com/product_variation1.html',
            imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
            price: 1.65,
            sku: 'sku-234',
            currency: 'currency',
            description: 'description',
            salePrice: 1.5,
            categories: [
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group', replace: true }],
            extraData: {  
                'string value': 'hello world',  
                'float value': 1.12,
                'boolean value': true
            },
            language: 'language',
            status: 'status',
            stock: 1,
            salePriceInclTax: 1.63
        },  
        {  
            id: 'var2',  
            image: 'http://www.image.com/image_b.jpg',  
            name: 'variation 2',  
            stock: 1,
            url: 'http://product.com/product_variation2.html',
            imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
            price: 1.65,
            sku: 'sku-234',
            currency: 'currency',
            description: 'description',
            salePrice: 1.5,
            categories: [
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group', replace: true }],
            extraData: {  
                'string value': 'hello world',  
                'float value': 1.12,
                'boolean value': true
            },
            language: 'language',
            status: 'status',
            stock: 1,
            salePriceInclTax: 1.63
        }  
    ]  
});

ddg.productList([product])

Tracks a list of products viewed by the contact.

Parameters

An array of product objects.

Example

window.ddg.productList(  
    [  
        {  
            brand: 'brand name',  
            categories: [  
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group', replace:false }],  
            currency: 'currency',  
            description: 'description',  
            extraData: {  
                'string value': 'hello world',  
                'int value': 1542,  
                'float value': 1.12,  
                'boolean value': true  
            },
            personalization: {        
                 siteBrand: "US"
            },
            imageThumbnailUrl: 'http://www.image.com/thumbnail.jpg',  
            imageUrl: 'http://www.image.com/image.jpg',  
            language: 'language',
            name: 'product 1',
            options: {
               “Option 1”: 5,
               “Option 2”: “Sam”
            }, 
            price: 1.12,  
            priceInclTax: 1.35,  
            productId: 'product id',  
            salePrice: 3.2,  
            salePriceInclTax: 3.5,  
            sku: 'sku-123',  
            status: 'status',  
            stock: 1,  
            url: 'http://product.com/product.html',  
            variantId: 'var1',  
            variants: [  
                {  
                    id: 'var1',  
                    image: 'http://www.image.com/image_a.jpg',  
                    name: 'variation 1',
                    stock: 1,
                    url: 'http://product.com/product_variation1.html',
                    imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
                    price: 1.65,
                    sku: 'sku-234',
                    currency: 'currency',
                    description: 'description',
                    salePrice: 1.5,
                    categories: [
                        'category 1',  
                        { categoryName: 'category 3', groupName: 'category group', replace: true }],
                    extraData: {  
                        'string value': 'hello world',  
                        'float value': 1.12,
                        'boolean value': true
                    },
                    language: 'language',
                    status: 'status',
                    stock: 1,
                    salePriceInclTax: 1.63
                 },  
                 {  
                    id: 'var2',  
                    image: 'http://www.image.com/image_b.jpg',  
                    name: 'variation 2',  
                    stock: 1,
                    url: 'http://product.com/product_variation2.html',
                    imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
                    price: 1.65,
                    sku: 'sku-234',
                    currency: 'currency',
                    description: 'description',
                    salePrice: 1.5,
                    categories: [
                        'category 1',  
                        { categoryName: 'category 3', groupName: 'category group', replace: true }],
                    extraData: {  
                        'string value': 'hello world',  
                        'float value': 1.12,
                        'boolean value': true
                    },
                    language: 'language',
                    status: 'status',
                    stock: 1,
                    salePriceInclTax: 1.63
                }  
            ]  
        },  
        {  
            brand: 'brand name',  
            categories: [  
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group', replace:false }],  
            currency: 'currency',  
            description: 'description',  
            extraData: {  
                'string value': 'hello world',  
                'int value': 1542,  
                'float value': 1.12,  
                'boolean value': true  
            },
            personalization: {
                 siteBrand: "US"
            },
            imageThumbnailUrl: 'http://www.image.com/thumbnail.jpg',  
            imageUrl: 'http://www.image.com/image.jpg',  
            language: 'language',  
            name: 'product 2',
            options: {
               “Option 1”: 5,
               “Option 2”: “Sam”
            }, 
            price: 1.12,  
            priceInclTax: 1.35,  
            productId: 'product id 2',  
            salePrice: 3.2,  
            salePriceInclTax: 3.5,  
            sku: 'sku-123',  
            status: 'status',  
            stock: 1,  
            url: 'http://product.com/product.html',  
            variantId: 'var1',  
            variants: [  
                {  
                    id: 'var1',  
                    image: 'http://www.image.com/image_a.jpg',  
                    name: 'variation 1',
                    stock: 1,
                    url: 'http://product.com/product_variation1.html',
                    imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
                    price: 1.65,
                    sku: 'sku-234',
                    currency: 'currency',
                    description: 'description',
                    salePrice: 1.5,
                    categories: [
                        'category 1',  
                        { categoryName: 'category 3', groupName: 'category group', replace: true }],
                    extraData: {  
                        'string value': 'hello world',  
                        'float value': 1.12,
                        'boolean value': true
                    },
                    language: 'language',
                    status: 'status',
                    stock: 1,
                    salePriceInclTax: 1.63
               },  
               {  
                    id: 'var2',  
                    image: 'http://www.image.com/image_b.jpg',  
                    name: 'variation 2',  
                    stock: 1,
                    url: 'http://product.com/product_variation2.html',
                    imageThumbnailUrl: 'http://www.image.com/image_b.jpg',
                    price: 1.65,
                    sku: 'sku-234',
                    currency: 'currency',
                    description: 'description',
                    salePrice: 1.5,
                    categories: [
                        'category 1',  
                        { categoryName: 'category 3', groupName: 'category group', replace: true }],
                    extraData: {  
                        'string value': 'hello world',  
                        'float value': 1.12,
                        'boolean value': true
                    },
                    language: 'language',
                    status: 'status',
                    stock: 1,
                    salePriceInclTax: 1.63
                }  
            ]  
        }  
    ]  
);

ddg.cartUpdate(cartDetails)

cartDetails object

📘
The cartDetails object can also be included with other methods, and follows the same structure as detailed below.

Name	Type	Description	Required
cartId	string	Unique identifier for the cart	Yes
cartPhase	string	Status of the cart	Yes, but is automatically set based on method* Ignored if passed to `purchaseComplete()`.
currency	string	Currency code in ISO 4217 format	Yes
subtotal	number	Subtotal amount	Yes
shipping	number	Shipping cost	No
discountAmount	number	Discount amount	No
taxAmount	number	Tax amount	No
grandTotal	number	Grand total amount	Yes
cartUrl	string	URL of the cart page	Yes
products	array[cartProduct]	Cart product objects	Yes
extraData	object	Additional data related to the cart.	No

*You can choose the value to send for cartPhase, but suggested values are ORDER_PENDING, ORDER_CHECKOUT, ORDER_COMPLETE, or CUSTOMER_LOGIN.

If no value is specified, then for ddg.cartUpdate we set cartPhase to ORDER_PENDING and for ddg.purchaseComplete we set it to ORDER_COMPLETE.

cartProduct object

Name	Type	Description	Required
productId	string	Unique identifier for the product	Yes
sku	string	Stock Keeping Unit.	Yes
name	string	Name of the product.	Yes
description	string	Description of the product.	No
extraData	object	Additional data related to the product.	No
personalization>siteBrand	string	The Dotdigital Personalization siteBrand for the product.	No siteBrand must be set in the configuration call. If siteBrand is set at the product level, this takes precedence.
options	object	Additional product-related data specific to the customer. Persists only for the session.	No
unitPrice	number	Price per unit.	Yes
unitPriceInclTax	number	Price per unit including tax.	No
salePrice	number	Sale price .	No
salePriceInclTax	number	Sale price including tax.	No
quantity	number	Quantity of products added to cart.	Yes
totalPrice	number	Total price.	No
totalPriceInclTax	number	Total price including tax.	No
imageUrl	string	Full URL of the product thumbnail image.	Yes
productUrl	string	Full URL of the product page.	Yes
variantId	string	Unique identifier of the variant.	No, but recommended

Example

window.ddg.cartUpdate({
  cartId: "123ABCZZFSEFSEFESZZZZZee",
  currency: "USD",
  subtotal: 35.98,
  shipping: 8,
  discountAmount: 0,
  taxAmount: 0,
  grandTotal: 35.98,
  cartUrl: "https://www.example.com/checkout/cart",
  products: [
    {
      productId: 'uniqueproductid',
      sku: "576879",
      name: "Shirt",
      options: {
            “Option 1”: 5,
            “Option 2”: “Sam”
      }, 
      description: "A super great description of the product",
      categories: ["Shirts", "T-Shirts", "Blue"],
      extraData: {"fieldName": "This can be a string or any value you like"},
      personalization: {
             siteBrand: "US"
      },
      price: 11.99,
      salePrice: 11.99,
      quantity: 20,
      totalPrice: 23.98,
      imageUrl: "http://www.example.com/a/p/shirt.jpeg",
      url: "http://www.example.com/index.php/shirt.html"
    }
  ]
});

ddg.checkout(cartDetails)

Tracks checkout events.

📘
When this method is used, the cartinsight's CartPhase in Dotdigital Marketing is set to ORDER_CHECKOUT .

You need to pass a cartDetails object that represents the cart being checked out.

Example

window.ddg.checkout({
  cartId: "123ABCZZFSEFSEFESZZZZZee",
  currency: "USD",
  subtotal: 35.98,
  shipping: 0,
  discountAmount: 0,
  taxAmount: 0,
  grandTotal: 35.98,
  cartUrl: "https://www.example.com/checkout/cart",
  products: [
    {
      productId: 'uniqueproductid',
      sku: "576879",
      name: "Shirt",
      options: {
           “Option 1”: 5,
           “Option 2”: “Sam”
      }, 
      description: "A super great description of the product",
      categories: ["Shirts", "T-Shirts", "Blue"],
      extraData: {"fieldName": "This can be a string or any value you like"},
      personalization: {
            siteBrand: "US"
      },
      unitPrice: 11.99,
      salePrice: 11.99,
      quantity: 20,
      totalPrice: 23.98,
      imageUrl: "http://www.my-website.com/a/p/shirt.jpeg",
      url: "http://www.my-website.com/index.php/shirt.html"
    }
  ]
});

ddg.purchaseComplete(cartDetails)

Tracks purchase completion events.

📘
This method can be used to generate order Insight records in Dotdigital Marketing if you aren’t otherwise syncing orders into Marketing.
When this method is used, the cartinsight's CartPhase in Marketing is set to ORDER_COMPLETE .
Learn more in Set up the Dotdigital Tag: Advanced settings.

Unlike cartUpdate and checkout, purchaseComplete takes a wrapping object containing an orderId and a nested cart object.

purchaseDetails object

Name	Type	Description	Required
orderId	string	Unique identifier for the completed order.	Yes
cart	cartDetails	The cart that was purchased.	Yes

Example

window.ddg.purchaseComplete({
  orderId: "45645",
  cart: {
    cartId: "123ABCZZFSEFSEFESZZZZZee",
    currency: "USD",
    subtotal: 35.98,
    shipping: 0,
    discountAmount: 0,
    taxAmount: 0,
    grandTotal: 35.98,
    cartUrl: "https://www.my-website.com/checkout/cart",
    products: [
      {
        productId: 'uniqueproductid',
        sku: "576879",
        name: "Shirt",
        options: {
            “Option 1”: 5,
            “Option 2”: “Sam”
        }, 
        description: "A super great description of the product",
        categories: ["Shirts", "T-Shirts", "Blue"],
        extraData: {"fieldName": "This can be a string or any value you like"},
        personalization: {
            siteBrand: "US"
        },
        price: 11.99,
        salePrice: 11.99,
        quantity: 20,
        totalPrice: 23.98,
        imageUrl: "http://www.my-website.com/a/p/shirt.jpeg",
        url: "http://www.my-website.com/index.php/shirt.html"
      }
    ]
  }
});

ddg.event(eventName, attributes)

📘
Custom events are only available to Dotdigital Marketing accounts on the CXDP package.

Sends custom events defined by you. These are automatically added to an Insight data collection of the same name as your event name/type.

🚧
Ensure you use the same event name/type for events of the same type so that they are collated into the same Insight data collection for easy reference.

Parameters

Name	Type	Description	Required
name	string	The name/type of the event being tracked.	Yes
data	object	An object containing any additional event attributes that may be useful.	Yes
timelineSummary	string	String value, to appear on the Single customer view timeline.	No

Example

Raising custom events whenever a customer searches for a holiday destination in a website.

window.ddg.event("Search destination", {
  "query":"Bali",
  "travel_from_date" : "2025-07-03"
});

Result: Insight collection: Search_destination Insight collection type: event

Insight record:

{
  "id": "5dbe0b01-c0d0-423e-a457-5c9d49d6e5b6",
  "event": "Search destination",
  "created_date": "2025-05-13T14:07:30.64Z",
  "attributes": {
    "query": "Bali",
    "travel_from_date": "2025-07-03"
  }
}

ddg.setCookiesConsent(true|false)

This method is used to indicate whether the Dotdigital Tag can save cookies to the browser or not.

It should be used in conjunction with your cookie consent manager and called whenever the visitor’s permission to store cookies changes, to ensure the Dotdigital Tag honors those settings correctly.

Parameters

A simple Boolean value where:

true - indicates that the Dotdigital Tag can save cookies.
false - indicates that the Dotdigital Tag cannot save cookies.

Example

window.ddg.setCookiesConsent(true) // Cookies are allowed.
window.ddg.setCookiesConsent(false) // Cookies are not allowed.