Event: Click

The Click Event is designed to track unique clicks on user interface elements powered by Particular Audience. These include product display slots, call to action buttons, and sort/filters in search.

This event categorizes actions through ActionType which specifies the type of interaction, and ContextType which identifies the type of widget being interacted with.

Click events are essential for tracking interactions related to Retailer Boost Collections and Supplier Funded Retail Media Campaigns, making them crucial for Analytics in Discovery OS.

Method: POST
URL: https://<PA_END_POINT>/3.0/events/clicks
Headers:
- Content-Type: application/json
- Authorization: Bearer ACCESS_TOKEN
Request Body Parameters:
- customerId (GUID) [REQUIRED]: 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) [REQUIRED]: 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 detailing Click event. Each Click event object will contain following properties:
  - currentUrl (string) [REQUIRED]: The URL where the Click event occurred.
  - eventTime (dateTime) [REQUIRED]: UTC timestamp of when the click happened.
  - clickId (GUID) [REQUIRED]: Unique identifier for the click event. This needs to be generated on the client side.
  - 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.
  - actionType (integer) [REQUIRED]: Identifier for the type of action taken. Please refer to the Action Types for more information.
  - contextType (integer) [REQUIRED]: 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.
  - redirectUrl (string): URL to which the user is taken to after the click.
    
    note
    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.
  - slot (integer): Slot number where the product was displayed. This is important for tracking the performance of the slot (especilly 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.
  Route, Widget & Tactic
  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.
  - routeId (GUID) [REQUIRED]: Identifier of the route where the widget was displayed (if applicable).
  - widgetId (GUID) [REQUIRED]: Identifier for the widget from which the product was added (if applicable).
  - recommenderId (GUID): Identifier of the recommender that populated the slot (if applicable).
  - campaignId (GUID): Identifier of the campaign that populated the slot (if applicable).
  - tacticId (GUID): Identifer of the tactic that populated the slot (if applicable).
  Retailer Boost Campaign
  The following properties are related to the Retailer Boost event tracking and are required to be sent as part of the event object in the payload for Retailer Boost analytics and reporting.
  - 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 required to be sent as part of the event object in the payload for Retail Media analytics and spend calculation.
  - 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.
  - 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 click event. This is provided as part of the slot data for the product in the Recommendations API response payload.
    
    note
    The keywordId is only required if the Retail Media slot was populated as part of the Keyword Targeting campaign.
  - keywordId (GUID): Client generated Id. If a slot was displayed as part of the Retail Media Keyword Targeting campaign, this field should be populated with the keywordId. The keywordId is generated as part of the search-keywords event. The search-keywords event is triggered when the Recommendations API is called with a specific keyword to retrieve the Retail Media slots for that keyword.

Here is an example 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,
      "contextData": "Camera",
      "redirectUrl": "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
      "referralUrl": "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
      "personalized": true,
      "widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "routeId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",

      // The following are only relevant to the Retailer Boost event tracking
      "retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",

      // The following are only relevant to the Retail Media event tracking
      "adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
      "adSetVersion": 1,
      "costPerClick": 0.5,
      "timeStamp": 638481477292391000,
      "hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
      "hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
      "keywordId": "xxxxxxxxxxxxxxxxxxxxxxx"        
    }
  ]
}

Returned Payload:

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"
}

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. Here is an example -

{
  "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"
}

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,
      contextType: 1,
      contextData: "Camera",
      redirectUrl: "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
      referralUrl: "https://www.example.com/xxxxxxxxxxxxxxxxxxxxxxx",
      personalized: true,
      widgetId: "xxxxxxxxxxxxxxxxxxxxxxx",
      routeId: "xxxxxxxxxxxxxxxxxxxxxxx",
      recommenderId: "xxxxxxxxxxxxxxxxxxxxxxx",
      campaignId: "xxxxxxxxxxxxxxxxxxxxxxx",
      tacticId: "xxxxxxxxxxxxxxxxxxxxxxx",

      // The following are only relevant to the Retailer Boost event tracking
      retailBoostCollectionCampaignId: "xxxxxxxxxxxxxxxxxxxxxxx",

      // The following are only relevant to the Retail Media event tracking
      adSetId: "xxxxxxxxxxxxxxxxxxxxxxx",
      adSetVersion: 1,
      costPerClick: 0.5,
      timeStamp: 638481477292391000
      hmacSalt: "xxxxxxxxxxxxxxxxxxxxxxx",
      hmac: "xxxxxxxxxxxxxxxxxxxxxxx",
      keywordId: "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));

Summary:

This document provides details about the Click Event API, including its design, essential parameters, and example payload.

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 method for this API is POST, and the URL is https://<PA_END_POINT>/3.0/events/clicks.
Request body parameters include customer ID, session ID, events array with checkout details, and responses are provided upon successful update or errors.
Action Types and Context Types are defined with their respective values and requirements.

Action Types

Name	Value
OpenProductPage	1
AddProductToCart	2
SeeSimilar	3
OpenProductListPage	4
PopularSearchLink	5
QuickLink	6
OpenBrandPage	7
TextLink	8
AddProductToWishlist	9
ClickBuyNow	10
ClickExternalBuyNow	11
ClickPhoneNumber	12
ViewInformation	13
ClickFilterSort	14
ClickDidYouMeanTerm	15
CloseModal	16
OpenPriceBeatModal	17

Context Types

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.

Event: Click

Action Types​

Context Types​

Action Types

Context Types