Event: Slot Impression

The Slot Impression API captures user interactions with product recommendation slots, tracking engagement and performance of PA powered widgets.

These impressions are crucial for engagement analytics and A/B testing.

Method: POST
URL: <https://<PA_END_POINT>/3.0/events/slot-impressions
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 Slot Impression event. Each Slot Impression event object will contain following properties:
  - currentUrl (string) [REQUIRED]: URL where the Slot Impression occured.
  - eventTime (dateTime) [REQUIRED]: UTC time when the slot was displayed.
  - refId (string) [REQUIRED]: Reference ID of the product being viewed.
  - widgetId (GUID) [REQUIRED]: 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) [REQUIRED]: 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.
  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 for the keyword. This is the amount the retailer is willing to pay for each click on the ad. 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 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": "xxxxxxxxxxxxxxxxxxx",
    "sessionId": "xxxxxxxxxxxxxxxxxxx",
    "events": [
        {
            "currentUrl": "https://www.example.com/product",
            "eventTime": "2024-04-15T02:20:00.000Z",
            "refId": "20037",
            "widgetId": "xxxxxxxxxxxxxxxxxxx",
            "routeId": "xxxxxxxxxxxxxxxxxxx",              
            "recommenderId": "xxxxxxxxxxxxxxxxxxx",
            "campaignId": "xxxxxxxxxxxxxxxxxxx",
            "tacticId": "xxxxxxxxxxxxxxxxxxx",

            // 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].refId": [
          "Product must contain a RefId"
      ]
  },
  "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/slot-impressions';
const body = {
  customerId: '4ea6c417-17d3-4d1c-9aaf-ace24a162caa',
  sessionId: '94945b41-d5f6-41d7-b978-c627fab40466',
  events: [
    {
      currentUrl: "https://www.example.com/",
      eventTime: "2024-03-01T14:00:00.000Z",
      refId: "61680",
      widgetId: "xxxxxxxxxxxxxxxxxxx",
      routeId: "xxxxxxxxxxxxxxxxxxx",
      recommenderId: "xxxxxxxxxxxxxxxxxxx",
      campaignId: "xxxxxxxxxxxxxxxxxxx",
      tacticId: "xxxxxxxxxxxxxxxxxxx",

      // 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 YOUR_ACCESS_TOKEN`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(body)
})
  .then(response => response.json())
  .then(data => console.log('Slot Impression Recorded:', data))
  .catch(error => console.error('Error recording slot impression:', error));

Summary:

This document is about the Slot Impression API, capturing user interactions and providing a method for recording slot impressions.

The API uses a POST method with specific URL and headers for sending request body parameters.
Request body parameters include customer and session identifiers, event details, and example payload structure.
Successful updates return a status code of '202' with an "Accepted" message, while errors provide relevant error messages.
A JavaScript code snippet demonstrates how to use the Fetch API to record slot impressions.