Using the Dotdigital Tag, you can capture events such as page views, user logins, product browsing and cart updates, and access this data across our platforms.

Purpose: These methods facilitate real-time data ingestion, supporting personalized marketing and analytics by mapping data to defined schemas.
Usage: They are called in JavaScript to track user actions and send data to a server endpoint.

📘
Before you start: These methods only work once the Dotdigital Tag has been installed on your site. See Add the Dotdigital Tag to your website for installation steps.

Calling methods safely

The Dotdigital Tag loads asynchronously, so window.ddg may not exist yet when your page first runs. If you call a method too early, your code will throw a TypeError.

You have two ways to call methods safely:

Wait for the ddgTagLoaded event before using window.ddg:

window.addEventListener("ddgTagLoaded", function () {
  window.ddg.track();
  window.ddg.identify({ email: "[email protected]" });
});

Use the window.dmPt(...) queue, which buffers calls until the tag is ready and replays them in order. This is useful when you don't have a convenient place to attach an event listener (for example, in a tag manager):
```
window.dmPt = window.dmPt || function () { (window.dmPt.q = window.dmPt.q || []).push(arguments); };
window.dmPt("identify", { email: "[email protected]" });
```

Errors are not surfaced to your code

All methods are fire-and-forget to avoid any issues interfering with your pages — they do not return a Promise and do not throw if the server rejects the request. To verify a call succeeded, inspect the network request in your browser's developer tools. A successful call returns 200; a 4xx response indicates a problem with the request or your tag configuration.

Data residency

The Dotdigital Tag automatically routes requests to the regional endpoint that matches your Dotdigital account. The region is derived from your profile ID and resolved to the corresponding r<N>.trackedweb.net host at runtime — no client-side configuration is required.

Key events

Event type	Method	Description
Set configuration	`window.ddg.configuration(data)`	Sets cartDelay and programId for abandoned cart enrolments. Also sets site details for Fresh Relevance, if required.
Page change	`window.ddg.track(data)`	Tracks page visits.
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 is set to `ORDER_CHECKOUT` .
Purchase complete	`window.ddg.purchaseComplete({...})`	Tracks purchase completion events. When used, the cart Insight data’s CartPhase in Dotdigital is set to `ORDER_COMPLETE` .
Custom event	`window.ddg.event("eventName",{...})`	Sends custom events defined by you.*

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

Method reference

ddg.configuration(data)

Sets cartDelay and programId for abandoned cart enrolments, as well as currency and language for the session. Also sets site brand for Fresh Relevance, 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.

Calls to configuration() are shallow-merged with any previous values. Fields you do not provide retain the value from the most recent call — they are not reset. This means it is safe to update a single value (e.g. cartDelay) without re-supplying the rest.

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.	No
personalization>siteBrand	string	The Fresh Relevance siteBrand for the session.	Yes If using Fresh Relevance.
site>language†	string	The site language for the user in ISO 3166 format.	Yes
site>currency†	string	The site currency in ISO 4217 format.	Yes

*Where marketing refers to Dotdigital, personalization refers to Fresh Relevance, and site refers to both platforms.

†For Fresh Relevance, these values must be consistent with other values in the product collection to avoid creating duplicate product records.

Example


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

ddg.track(pageData)

Tracks page visits.

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

Example

window.ddg.track({
  url: "https://example.com/checkout",
  title: "Cart checkout"
});

ddg.identify(identityDetails)

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

Note: This method will augment or update existing contacts but will not create new ones in Dotdigital!

identityDetails object

Name	Type	Description	Required
email	string	User's email address.	Conditional At least one of `email` or `mobileNumber` is required.
mobileNumber	string	User's mobile number in E.164 format.	Conditional At least one of `email` or `mobileNumber` is required.
firstName	string	User's first name. Used by Fresh Relevance only. Ignored by Dotdigital.	No
lastName	string	User's last name. Used by Fresh Relevance only. Ignored by Dotdigital.	No
fullName	string	User's full name. Used by Fresh Relevance only. Ignored by Dotdigital.	No

Example

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

ddg.getTrackedId()

Returns the Dotdigital Contact ID for the current visitor, if available. Returns undefined otherwise.

📘
Requires a visit using a tracked link
A contact ID is only available if the visitor previously arrived on your site via a Dotdigital tracking link (for example, from a marketing email or SMS) within the last hour. The link sets a short-lived (1 hour) dm_i cookie that this method reads.
Calling ddg.identify() does not populate the value returned by getTrackedId(). The two methods are independent: identify() tells Dotdigital who the visitor is, whereas getTrackedId() reports what Dotdigital already knew about them from an inbound tracked link.

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 full-size product image.	Yes
imageThumbnailUrl	string	Full URL of the product thumbnail image (smaller version, suitable for listings).	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
extraData	object	Additional data related to the product.	No
lang	string	Language code.	No
brand	string	Brand of the product.	No, but recommended
variantId	string	Unique identifier of the variant.	No, but recommended
variants	array[variant]	Array of product variants.	No, but recommended

variant object

Property name	Type	Required
id	string	Yes
url	string	Yes
name	string	Yes
stock	number	Yes
image	string	Yes

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

Example

window.ddg.productBrowse({  
    productId: 'uniqueproductid',  
    name: 'name',  
    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',  
    lang: 'language',  
    categories: [  
        'category 1',  
        { categoryName: 'category 3', groupName: 'category group' }],  
    currency: 'currency',  
    description: 'description',  
    extraData: {  
        'string value': 'hello world',  
        'int value': 1542,  
        'float value': 1.12,  
        'boolean value': true  
    },  
    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'  
        },  
        {  
            id: 'var2',  
            image: 'http://www.image.com/image_b.jpg',  
            name: 'variation 2',  
            stock: 1,  
            url: 'http://product.com/product_variation2.html'  
        }  
    ]  
});

ddg.productList([product])

Tracks a list of products viewed by the contact, typically on a category or collection landing page where multiple products are displayed together.

Parameters

An array of product objects.

Example

window.ddg.productList(  
    [  
        {  
            brand: 'brand name',  
            categories: [  
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group' }],  
            currency: 'currency',  
            description: 'description',  
            extraData: {  
                'string value': 'hello world',  
                'int value': 1542,  
                'float value': 1.12,  
                'boolean value': true  
            },  
            imageThumbnailUrl: 'http://www.image.com/thumbnail.jpg',  
            imageUrl: 'http://www.image.com/image.jpg',  
            lang: 'language',  
            name: 'product 1',  
            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'  
                },  
                {  
                    id: 'var2',  
                    image: 'http://www.image.com/image_b.jpg',  
                    name: 'variation 2',  
                    stock: 1,  
                    url: 'http://product.com/product_variation2.html'  
                }  
            ]  
        },  
        {  
            brand: 'brand name',  
            categories: [  
                'category 1',  
                { categoryName: 'category 3', groupName: 'category group' }],  
            currency: 'currency',  
            description: 'description',  
            extraData: {  
                'string value': 'hello world',  
                'int value': 1542,  
                'float value': 1.12,  
                'boolean value': true  
            },  
            imageThumbnailUrl: 'http://www.image.com/thumbnail.jpg',  
            imageUrl: 'http://www.image.com/image.jpg',  
            lang: 'language',  
            name: 'product 2',  
            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'  
                },  
                {  
                    id: 'var2',  
                    image: 'http://www.image.com/image_b.jpg',  
                    name: 'variation 2',  
                    stock: 1,  
                    url: 'http://product.com/product_variation2.html'  
                }  
            ]  
        }  
    ]  
);

ddg.cartUpdate(cartDetails)

cartDetails object

Name	Type	Description	Required
cartId	string	Unique identifier for the cart	Yes
cartPhase	string	Status of the cart. Defaults to a value based on which method you call — see note below.	No
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

cartPhase is automatically populated based on the method you call: ORDER_PENDING for ddg.cartUpdate, ORDER_CHECKOUT for ddg.checkout, and ORDER_COMPLETE for ddg.purchaseComplete. You can override it by passing a value explicitly. Suggested values are ORDER_PENDING, ORDER_CHECKOUT, ORDER_COMPLETE, or CUSTOMER_LOGIN.

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
categories	category \| array[category ]	Categories the product belongs to.	No, but recommended
extraData	object	Additional data related to the product.	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
brand	string	Brand of the product.	No, but recommended

*Only required for Fresh Relevance

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",
      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"},
      unitPrice: 11.99,
      salePrice: 11.99,
      quantity: 20,
      totalPrice: 23.98,
      imageUrl: "http://www.example.com/a/p/shirt.jpeg",
      productUrl: "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 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",
      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"},
      unitPrice: 11.99,
      salePrice: 11.99,
      quantity: 20,
      totalPrice: 23.98,
      imageUrl: "http://www.my-website.com/a/p/shirt.jpeg",
      productUrl: "http://www.my-website.com/index.php/shirt.html"
    }
  ]
});

ddg.purchaseComplete(purchaseDetails)

Tracks purchase completion events.

📘
This method can be used to generate order Insight records in Dotdigital if you aren’t otherwise syncing orders into Dotdigital.
When this method is used, the cartinsight's CartPhase in Dotdigital is set to ORDER_COMPLETE.
Learn more in Add the Dotdigital Tag to your website: 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",
        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"},
        unitPrice: 11.99,
        salePrice: 11.99,
        quantity: 20,
        totalPrice: 23.98,
        imageUrl: "http://www.my-website.com/a/p/shirt.jpeg",
        productUrl: "http://www.my-website.com/index.php/shirt.html"
      }
    ]
  }
});

ddg.event(eventName, attributes)

Custom events in Dotdigital are only available in our CXDP account 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
eventName	string	The name/type of the event being tracked.	Yes
attributes	object	An object containing any additional event attributes that may be useful. Pass an empty object (`{}`) if you have nothing to add.	Yes

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.

When consent is denied, the values that would otherwise be cookies are stored in sessionStorage instead, meaning they don't persist beyond the current browser tab.

Cookies set by the Dotdigital Tag

Name	Lifetime	Purpose
`recordID`	365 days	Anonymous visitor identifier used to stitch behaviour across sessions.
`dmSessionID`	~20 minutes	Current session identifier.
`dm_i`	~1 hour	Inbound contact reference captured from Dotdigital tracking links.
`utm_source`	Session	Captured UTM parameter, if present in the URL.
`utm_medium`	Session	Captured UTM parameter, if present in the URL.
`utm_campaign`	Session	Captured UTM parameter, if present in the URL.

Example

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