Event: Click
The Click Event tracks unique clicks on user interface elements powered by Particular Audience, such as product display slots, call-to-action buttons, and sort/filters in search.
This event categorizes actions through ActionType
(type of interaction) and ContextType
(type of widget being interacted with).
Click events are crucial for tracking interactions related to Retailer Boost Collections and Supplier Funded Retail Media Campaigns, essential for Analytics in Discovery OS.
API Endpoint
Method: POST
URL: https://<PA_END_POINT>/3.0/events/clicks
Request Header
Name | Value |
---|---|
Content-Type | application/json |
Authorization | Bearer ACCESS_TOKEN |
Request Parameters (Body)
Parameter | Type | Required | Description |
---|---|---|---|
customerId | GUID | ✅ | Unique identifier for the customer, obtained from the Config API. This identifier persists throughout the customer's lifetime on the platform. For details on retrieving a customer ID, please refer to the Config API documentation. |
sessionId | GUID | ✅ | Unique identifier for the session, consistent throughout the session's duration. For information on obtaining a session ID, please refer to the Config API documentation. |
events | Array of objects | ✅ | Array of objects detailing Click events. Each Click event object will contain the following properties: |
Event Object Definition
Parameter | Type | Required | Description |
---|---|---|---|
currentUrl | string | ✅ | URL where the click occurred. |
clickId | GUID | ✅ | Unique identifier for the click event. This needs to be generated on the client side. |
eventTime | dateTime | ✅ | UTC timestamp of when the click happened. |
widgetId | GUID | ✅ | Identifier for the widget the slot belongs to. This information is available as part of the Recommendations API response payload from where the slot's data was collected. |
routeId | GUID | ✅ | Route identifier that led to the widget display. This information is available as part of the Recommendations API response payload from where the slot's data was collected. |
actionType | integer | ✅ | Identifier for the type of action taken. Please refer to the Action Types for more information. |
contextType | integer | ✅ | Identifier for the type of context in which the click occurred. Please refer to the Context Types for more information. |
contextData | string | ❌ | Additional data about the context, can be simple text or JSON structured. The required content depends on the context type. |
contextId | string | ❌ | Identifier for the specific context. Required for some context types as detailed in the Context Types section. |
refId | string | ❌ | Product's refID . If the event is in reference to an individual product then the refId of the product. For example, a click event to view the product detail page or add-to-cart. However, if the click is not related to an individual product, exclude this field. |
tacticLabel | string | ❌ | Human-readable label for the tactic that populated the slot. |
recommenderId | GUID | ❌ | Identifier of the recommender that populated the slot. This information is available as part of the Recommendations API response payload from where the slot's data was collected. |
campaignId | GUID | ❌ | Identifier of the campaign that populated the slot. This information is available as part of the Recommendations API response payload from where the slot's data was collected. |
tacticId | GUID | ❌ | Identifier of the tactic that populated the slot. This information is available as part of the Recommendations API response payload from where the slot's data was collected. |
bannerId | GUID | ❌ | Identifier of the banner if the click is related to a banner element. |
placementId | GUID | ❌ | Identifier for the placement position where the click occurred. |
Route ID
, Widget ID
and Tactic ID
are important for tracking the performance and effectiveness of the recommendation strategies. These are available as part of the Recommendations API response payload from where the slot's data was collected. Please refer to the Recommendations API documentation and Personalization Overview page for more information.
Additional parameters:
Parameter | Type | Required | Description |
---|---|---|---|
clickPosition | integer | ❌ | Position of the clicked item within a list or grid (e.g., position 3 in search results). |
slot | integer | ❌ | Slot number where the product was displayed. This is important for tracking the performance of the slot (especially if the slot is related to Boosting or Retail Media campaigns). This is provided as part of the slot data for the product in the Recommendations API response payload. |
referralUrl | string | ❌ | URL from which the user was referred (if applicable). |
personalized | boolean | ❌ | Indicates whether the click was on a personalized Recommendation or Search result. |
redirectUrl | string | ❌ | URL to which the user is taken to after the click. |
The redirectUrl
tracking is very important for training the search engine and improving search performance. If you are using ATS, this is crucial for training the system. When a user clicks on a product from the search result, a Click event should be sent with the redirectUrl
as the product URL.
Retailer Boost Campaign
The following properties are related to the Retailer Boost event tracking and are used for Retailer Boost analytics and reporting.
Parameter | Type | Required | Description |
---|---|---|---|
retailBoostCollectionCampaignId | GUID | ❌ | The identifier of the Retailer Boost Collection Campaign . This is provided as part of the slot data for the product in the Recommendations API response payload. |
Retail Media
The following properties are related to the Retail Media event tracking and are used for Retail Media analytics and spend calculation.
Parameter | Type | Required | Description |
---|---|---|---|
adSetId | GUID | ❌ | The identifier of the Ad Set . This is provided as part of the slot data for the product in the Recommendations API response payload. |
adSetVersion | integer | ❌ | The version of the Ad Set . This is provided as part of the slot data for the product in the Recommendations API response payload. |
costPerClick | decimal | ❌ | The cost per click on a sponsored slot is provided as part of the slot data for the product in the Recommendations API response payload. |
costPerAction | decimal | ❌ | The cost per action on a sponsored slot, if applicable. This is provided as part of the slot data for the product in the Recommendations API response payload. |
costPerMille | decimal | ❌ | The cost per mille on a sponsored slot, if applicable. This is provided as part of the slot data for the product in the Recommendations API response payload. |
timeStamp | timestamp | ❌ | The timestamp provided as part of the product's slot data in the Recommendations API response payload. This is the timestamp when the slot was populated. |
hmacSalt | string | ❌ | String of 16 random characters generated by recommender. Used for calculating and validating HMAC field. This is provided as part of the slot data for the product in the Recommendations API response payload. |
hmac | string | ❌ | The hash-based message authentication code (HMAC) generated using the adSetId , hmacSalt , costPerClick , timeStamp . This is used to validate the authenticity of the slot impression event. This is provided as part of the slot data for the product in the Recommendations API response payload. |
supplierId | GUID | ❌ | The identifier of the supplier associated with the retail media campaign. |
keywordId | GUID | ❌ | Client generated Id. Required if the Retail Media slot was populated as part of a Keyword Targeting campaign. Generated as part of the search-keywords event. |
If sending Retail Media tracking data, the cost parameters, timestamp, and HMAC-related fields are recommended to be included for proper analytics.
The keywordId
is only needed if the Retail Media slot was populated as part of a Keyword Targeting campaign. The keywordId
is generated as part of the search-keywords
event triggered when the Recommendations API is called with a specific keyword.
Example Request Payload
{
"customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
"sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
"events": [
{
"currentUrl": "https://www.example.com/",
"eventTime": "2024-03-01T14:00:00.000Z",
"clickId": "xxxxxxxxxxxxxxxxxxxxxxx",
"refId": "231673",
"actionType": 1,
"contextType": 1,
"contextId": "xxxxxxxxxxxxxxxxxxxxxxx",
"contextData": "Camera",
"redirectUrl": "https://www.example.com/product/camera",
"referralUrl": "https://www.example.com/search",
"personalized": true,
"clickPosition": 3,
"widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
"routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
"recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
"campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
"tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",
"tacticLabel": "Featured Products",
"bannerId": "xxxxxxxxxxxxxxxxxxxxxxx",
"placementId": "xxxxxxxxxxxxxxxxxxxxxxx",
// Retailer Boost event tracking
"retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
// Retail Media event tracking
"adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
"adSetVersion": 1,
"costPerClick": 0.5,
"costPerAction": 1.0,
"costPerMille": 0.25,
"timeStamp": 638481477292391000,
"hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
"hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
"keywordId": "xxxxxxxxxxxxxxxxxxxxxxx",
"supplierId": "xxxxxxxxxxxxxxxxxxxxxxx"
}
]
}
Response
On Success
On successful update, the returned status code will be 202
, and the payload will contain the status message "Accepted" and a transaction ID.
{
"transactionId": "xxxxxxxxxxxxxxxxxxxxxxx",
"status": "Accepted"
}
On Error
If there are any errors, the response status code will not be 202
, and the relevant error messages will be provided as part of "errors" in the returned message.
{
"errors": {
"events[0].CurrentUrl": [
"'Current Url' must not be empty."
]
},
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "One or more validation errors occurred.",
"status": 400,
"traceId": "xxxxxxxxxxxxxxxxxxx"
}
Example Usage (JavaScript)
Here's an example code snippet using JavaScript's Fetch API:
const url = 'https://<PA_END_POINT>/3.0/events/clicks';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
customerId: 'xxxxxxxxxxxxxxxxxxxxxxx',
sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
events: [
{
currentUrl: "https://www.example.com/",
eventTime: "2024-03-01T14:00:00.000Z",
clickId: "xxxxxxxxxxxxxxxxxxxxxxx",
refId: "12312",
actionType: 1, // OpenProductPage
contextType: 3, // SearchWidget
contextId: "xxxxxxxxxxxxxxxxxxxxxxx",
contextData: "Camera", // Search Term
redirectUrl: "https://www.example.com/product/camera",
personalized: true,
clickPosition: 2,
widgetId: "xxxxxxxxxxxxxxxxxxxxxxx",
routeId: "xxxxxxxxxxxxxxxxxxxxxxx",
// Retail Media event tracking
adSetId: "xxxxxxxxxxxxxxxxxxxxxxx",
adSetVersion: 1,
costPerClick: 0.5,
timeStamp: 638481477292391000,
hmacSalt: "xxxxxxxxxxxxxxxxxxxxxxx",
hmac: "xxxxxxxxxxxxxxxxxxxxxxx"
}
]
};
fetch(url, {
method: 'POST',
headers: {
"Authorization": `Bearer ${accessToken}`,
"Content-Type": "application/json"
},
body: JSON.stringify(body)
})
.then(response => response.json())
.then(data => console.log('Click Recorded:', data))
.catch(error => console.error('Error recording click:', error));
Action Types
The following action types define the specific user interaction being tracked:
Name | Value | Description |
---|---|---|
OpenProductPage | 1 | User clicked to view a product detail page |
AddProductToCart | 2 | User clicked to add a product to their shopping cart |
SeeSimilar | 3 | User clicked a "See Similar" or related products link |
OpenProductListPage | 4 | User clicked to view a product listing page |
PopularSearchLink | 5 | User clicked on a popular or suggested search term |
QuickLink | 6 | User clicked on a quick navigation link |
OpenBrandPage | 7 | User clicked to view a brand page |
TextLink | 8 | User clicked on a text hyperlink |
AddProductToWishlist | 9 | User clicked to add a product to their wishlist |
ClickBuyNow | 10 | User clicked a "Buy Now" button |
ClickExternalBuyNow | 11 | User clicked to buy from an external vendor |
ClickPhoneNumber | 12 | User clicked on a phone number link |
ViewInformation | 13 | User clicked to view additional product information |
ClickFilterSort | 14 | User clicked on filter or sort options |
ClickDidYouMeanTerm | 15 | User clicked on a "Did You Mean" suggestion for a misspelled search |
CloseModal | 16 | User clicked to close a modal or popup |
Context Types
The context type defines the type of widget or element where the click occurred:
Name | Value | ContextId Required? | ContextData Required? |
---|---|---|---|
RecommendationWidget | 1 | Yes. Value: Id of the Widget | No |
VisualSearchWidget | 2 | Yes. Value: VisualSearchWidget event id | No |
SearchWidget | 3 | Yes. Value: TextSearchEventId | Yes. Search Term |
NativeRecommendationWidget | 4 | Yes. Native Widget Id | No |
ExitIntentWidget | 5 | No | No |
PersonalizeWidget | 6 | No | No |
PersonaliseBrandWidget | 7 | No | No |
BundleWidget | 8 | No | No |
PriceBeatWidget | 9 | No | No |
KeywordTargetingWidget | 10 | No | No |
NativeButton | 11 | No | No |
Summary
This document provides comprehensive details about the Click Event API, essential for tracking user interactions:
- The Click Event API tracks unique clicks on user interface elements powered by Particular Audience
- It categorizes actions through ActionType and ContextType, crucial for PA Advanced Analytics
- The endpoint uses a POST method with URL
https://<PA_END_POINT>/3.0/events/clicks
- Required parameters include customer ID, session ID, click ID, and details about the click action and context
- Additional parameters support retail media, retail boost tracking, and enhanced analytics
- Special fields like bannerId, placementId, and clickPosition provide more context about user interactions
- The API returns a 202 status code with a transaction ID on successful recording
- Error responses include relevant error messages and a 400 status code
- A comprehensive list of action types and context types is provided for accurate classification
- The JavaScript example demonstrates how to implement the API call in your application