Tracking Implementation Guide

Getting you up to speed with the required tracking you'll need to make full use of our Product Discovery features.

If you are using (XO) Recommendations: To kickstart the algorithms we would highly recommend providing a sales history as described here: Sales History

Basic

Activity	When to trigger	Mandatory
Click	When a user clicks on a product.
Click on Search Result	When a user clicks on a product from an SRP.
View	When a user views a PDP.
View on Search Result/Navigation	When a user views a product directly from an SRP/PLP.
Add to Cart	When a user adds a product to their cart directly from a PDP page.
Add to Cart on Search Result/Navigation	When a user adds a product to their cart directly from an SRP/PLP.
Remove from Cart	When a user removes a product from their cart.
Purchase/Buy	When a user purchases an item. (These must be sent per item within an order).

XO Specific

Activity	When to trigger	Mandatory
Click on Recommendation	When a user clicks a product within a recommendation.

FHR Specific

Activity	When to trigger	Mandatory
Click on Campaign	When a user clicks on a product within a campaign.
Click on Facet	When a user clicks on a facet.

Activity Structure

More information regarding the activity structure can be found here: What is an Activity

Activities are composed of the following structure:

{ 
    "action": {action_type},
    "target": {target},
    "sourceId": {sourceId},
    "user": {"identities": {identities}} 
    "metadata": {metadata}
}

Mandatory fields

When sending an activity it is fundamental that the following fields are always populated:

Field	Type	Description
action	String	This is the type of action the user has performed, this can be: - click - view - add-to-cart - purchase
target	Object	The target of the users action, this can be either a product or page i.e. {"product": "productId"} OR {"page": "fullPagePath"}.
sourceId	String	The id of the previous request on the page used to fetch the data. For example, if the request is made on a PLP this will be the id of the request used to drive that PLP.
user.identities	Object	The ids used to distinguish a customer, this can be: {"ecommerceId": "customerId"} Please discuss how you distinguish your customers with your TC to set this up appropriately.

Please see Managing identitiesfor further information on what is stored in the user object.

Non-mandatory fields

Field	Type	Description
metadata	Object	This is populated with information required for the activity to function. Below you will find what metafields are required for each activity type.

Metadata Object

The metadata object can contain the following variables:

Field	Type	Description
quantity	Integer	The number of products a customer has bought.
orderId	String	The id of the order made.
widgetId	String	The id of the widget called to fetch the recommendations.
locale	String	The locale of the store e.g. "en_GB".
price	Integer	The price of the product in cents/pence. If you use a float/currency type please be sure to times by 100.
currency	String	The currency type e.g. "USD".

You can also use metadata to store additional information about the activity.

Examples

Basic Activity Example Requests

Click

Triggered when a user clicks on a product

Click on Product (Mandatory)

const clickActionOnProduct = {
    "action":"click",
    "target": {
        "product": "83647582"
    },
    "sourceId":"8efbbef2-6640-4c16-b263-1f5a84813a1c",
    "metadata": {
        "locale": "en_GB"
    }
}

xo.activity.send(clickActionOnProduct);

Click on Search Result

const clickOnSearchResults = {
 "action": "click",
 "target": {
   "product": "83647582"
 },
 "sourceId": "8efbbef2-6640-4c16-b263-1f5a84813a1c",
 "metadata": {
   "query": "User typed keyword"
 }
}

xo.activity.send(clickOnSearchResults);

View

Triggered when a user clicks on a product

View Product (Mandatory)

const viewActionOnProduct = {
    "action":"view",
    "target": {
        "product":"83647582"
    },
    "sourceId":"6266c5de-6a3c-4299-af78-3fd17dc3e787",
    "metadata": {
        "locale": "en_GB"
    }
}

xo.activity.send(viewActionOnProduct);

View on Search Result (Fredhopper)

const viewActionOnSearchResult = {
    "action":"view",
    "target": {
        "page": "path/to/page"
        "search-terms": "trousers"
    },
    "sourceId":"8efbbef2-6640-4c16-b263-1f5a84813a1c",
    "metadata": {
        "locale": "en_GB"
    }
}

xo.activity.send(viewActionOnSearchResult);

View on Navigation Result (Fredhopper)

const viewActionOnNavigationResult = {
    "action":"view",
    "target": {
        "page": "path/to/page"
    },
    "sourceId":"f9caf9db-7549-4498-8c2a-3be977ce48d9",
    "metadata": {
        "locale": "en_GB"
    }
}

xo.activity.send(viewActionOnNavigationResult);

View on Search Result (XO)

const searchOnSRP = {
 "action": "view",
 "sourceId": "metadata.id",
 "target": {
     "pathToPage": "www.attraqt.com/my-page/"
   },
 "metadata": {
   "query": "KEYWORD"
 }
}

xo.activity.send(searchOnSRP);

View on Navigation Result (XO)

const searchOnPLP = {
 "action": "view",
 "target": {
   "pathToPage": "www.attraqt.com/my-page/"
 },
 "sourceId": "metadata.id",
 "metadata": {
 }
}

xo.activity.send(searchOnPLP);

Add to Cart

Trigger when a user adds a product to their cart

Add to Cart (Mandatory)

const addToCartAction = {
    "action":"add-to-cart",
    "target": {
        "product":"83647582"
    },
    "metadata": {
        "quantity": 1,
        "locale": "en_GB"
    },
    "sourceId": "5f0dfaf1-c79a-47fd-982f-b17de6533cf3"
}

xo.activity.send(addToCartAction);

Add to Cart on Search Result/Navigation (Fredhopper)

const addToCartAction = {
    "action":"add-to-cart",
    "target": {
        "product":"83647582"
    },
    "metadata": {
        "quantity": 1,
        "locale": "en_GB"
    },
    "sourceId": "5f0dfaf1-c79a-47fd-982f-b17de6533cf3"
}

xo.activity.send(addToCartAction);

Add to Cart on Search Result/Naviagtion (XO)

const addToCartAction = {
  "action": "add-to-cart",
  "target": {
    "product": "83647582"
  },
  "sourceId": "8b0dfaf1-c79a-47fd-982f-b17de6533cf3",
  "metadata": {
    "query": "Necklace", // optional
    "price": 0,
    "currency": "GBP",
    "quantity": 1,
    "variant": "83647584" //optional
  }
}

xo.activity.send(addToCartAction);

Remove from Cart

Remove from Cart

const removeFromCartAction = {
    "action":"remove-from-cart",
    "target": {
        "product":"83647582"
    },
}

xo.activity.send(removeFromCartAction);

Purchase

Triggered when a user purchases an item - this must be sent per product id

Purchase (Mandatory)

const purchaseAction = {
    "action":"purchase",
    "target": {
        "product":"83647582"
    },
    "metadata": {
        "orderId": "ec1851da-bff2-495c-b757-c162d9a079bd",
        "price": 3250, // Please be sure to make this an integer by * 100
        "quantity": 2,
        "currency": "EUR",
        "locale": "en_GB"
    }
}

xo.activity.send(purchaseAction);

XO Specific Activity Examples

Triggered when a user clicks on a product within a widget

Click on Recommendation (XO)

const clickActionOnRecommendation = {
 "action": "click",
 "target": {
   "product": "83647582"
 },
 "sourceId": "ec1851da-bff2-495c-b757-c162d9a079bd",
 "metadata": {
   "widgetId": "5f0dfaf1c79a47fd982fb17de6533cf3"
 }
}

xo.activity.send(clickActionOnRecommendation);

FHR Specific Activity Examples

Triggered when a user clicks on a campaign

Click on Campaign (Fredhopper)

const clickActionOnProductFromCampaign = {
    "action":"click",
    "target": {
        "product": "83647582",
        "campaign": "41234266-cf17-4ed3-8423-fbd029a3d7ae"
    },
    "sourceId":"8efbbef2-6640-4c16-b263-1f5a84813a1c",
    "metadata": {
        "locale": "en_GB"
    }
}

xo.activity.send(clickActionOnProductFromCampaign);

Triggered when a user clicks on a facet

Click on Facet (Fredhopper)

const clickActionOnFacet = {
  "action": "click",
  "target": {
    "facet": "28f909c0-332b-4afd-bd75-1e0e793e1984",
    "28f909c0-332b-4afd-bd75-1e0e793e1984": "red"
  },
  "sourceId": "8efbbef2-6640-4c16-b263-1f5a84813a1c",
  "metadata": {
    "locale": "en_GB"
  }
}

xo.activity.send(clickActionOnFacet);

API

Regardless of the method of implementation, the following API call will subsequently be made:

Send activity

POST https://collect-eu.attraqt.io/:trackerKey

Send an activity to the API

Path Parameters

Name	Type	Description
trackerKey	String	Tracker key uniquely identifying the application.

Request Body

Name	Type	Description
target	object	The target of the action
action	String	The user's action on the website
user	object	User object (traits, segments and identities)
sourceId	String	If the action is on a search result or a recommendation, then send the sourceId - responseId in FHR or recommendationId in XO
metadata	String	All additional contextual data on the performed action
segments	String	List of segments, usually for describing the client
timestamp	String	Timestamp in ISO format

201: Created Activity successfully sent

401: Unauthorized Failed to validate tracker key

422: Unprocessable Entity Failed to validate activity

Response

{ ​
  "profiles": ​{
  } ​
}

Unless you have AI Scores enabled, the response body will be as the above.

For more information regarding the AI scores response, please see here.

Feature Tracking Checklist

To be sure you have everything you need per feature please see the checklists below.

XO Recommendations Metrics

• Click on Product

• Click on Recommendation

• View on Product

• Add to Cart

• Purchase

Fredhopper/Insights

• Click on Product

• Click on Facet

• Click on Campaign (Only if you are using campaigns in your FHR setup)

• Click on Search/Navigation

• View on Product

• View on Search/Navigation

• Add to Cart

• Remove from Cart

• Purchase

AI Scores

• Click on Product

• Click on Search/Navigation

• View on Product

• View on Search/Navigation

• Add to Cart

• Purchase