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 and Fresh Relevance 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.

Learn more about the Dotdigital Tag.

Key events

Event type	Method	Description
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 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 are only available in the Dotdigital CXDP account package.

Method reference

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 Fresh Relevance, but is not automatically mapped to a custom ID field in Dotdigital. The value is stored is webInsight records in 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 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
extraData	object	Additional data related to the product.	No
lang	string	Language code in ISO 639 format.	No*
sbr	string	Site brand.	No*
variantId	string	Unique identifier of the variant.	No, but recommended
variants	array[variant]	Array of product variants.	No, but recommended

*If lang, currency , and sbr are included in your product sync to Fresh Relevance, 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

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',  
    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.

Parameters

An array of product objects.

Example

window.ddg.productList(  
    [  
        {   
            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'  
                }  
            ]  
        },  
        {   
            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

📘
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
categories	array[category]	Categories the product belongs to.	No, but recommended.
options	object	Customisation 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

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: [
        "category 1",
        { categoryName: "category 3", groupName: "category group" }
      ],
      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.

📘
Product data
Product data included in cart events use the same schema as the standard product object, with the additional fields for quantity and unitPrice.

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: [
        "category 1",
        { categoryName: "category 3", groupName: "category group" }
      ],
      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(cartDetails)

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 Set up the Dotdigital Tag: Advanced settings.

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

Example

window.ddg.purchaseComplete({
  cartId: "123ABCZZFSEFSEFESZZZZZee",
  orderId: "45645",
  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: [
        "category 1",
        { categoryName: "category 3", groupName: "category group" }
      ],
      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 are only available to Dotdigital 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.