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.

API Endpoint

Method: POST
URL: https://<PA_END_POINT>/3.0/events/slot-impressions

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 `Slot Impression` events. Each `Slot Impression` event object will contain the following properties:

Event Object Definition

Parameter	Type	Required	Description
`currentUrl`	`string`	✅	URL where the `Slot Impression` occurred.
`eventTime`	`dateTime`	✅	UTC timestamp of when the impression happened.
`refId`	`string`	✅	Reference ID of the product being viewed.
`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.
`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.
`tacticLabel`	`string`	❌	Label of the tactic that populated the slot, providing a human-readable descriptor.
`bannerId`	`GUID`	❌	Identifier of the banner if the impression is for a banner element.
`personalized`	`boolean`	❌	Indicates whether the recommendation was personalized for the user.
`placementId`	`GUID`	❌	Identifier for the placement position where the impression occurred.

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.
`costPerMille`	`decimal`	❌	The cost per mille on a sponsored slot 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, if applicable. This 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.
`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`, any of the cost fields, `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.

note

At least one of the cost parameters (costPerMille, costPerClick, or costPerAction) should be provided if sending Retail Media tracking data.

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.

Price Beat Parameters

The following properties are related to price beat functionality and are optional:

Parameter	Type	Required	Description
`priceBeat`	`Object`	❌	Object containing price beat information with the following properties: - `clientPaidPrice (decimal)`: The price paid by the client. - `competitorPrice (decimal)`: The competitor's price for the same product. - `clientOriginalPrice (decimal)`: The original price before any price beat adjustments. - `competitorId (string)`: Identifier for the competitor. - `priceBeatTrigger (string)`: What triggered the price beat logic.

Example Request Payload

{
    "customerId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "sessionId": "xxxxxxxxxxxxxxxxxxxxxxx",
    "events": [
        {
            "currentUrl": "https://www.example.com/product",
            "eventTime": "2024-04-15T02:20:00.000Z",
            "refId": "20037",
            "widgetId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "routeId": "xxxxxxxxxxxxxxxxxxxxxxx",              
            "recommenderId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "campaignId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "tacticId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "tacticLabel": "Featured Products",
            "bannerId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "personalized": true,
            "placementId": "xxxxxxxxxxxxxxxxxxxxxxx",

            // Retailer Boost event tracking
            "retailBoostCollectionCampaignId": "xxxxxxxxxxxxxxxxxxxxxxx",

            // Retail Media event tracking
            "adSetId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "adSetVersion": 1,
            "costPerMille": 0.5,
            "costPerClick": 0.25,
            "costPerAction": 1.0,
            "timeStamp": 638481477292391000,
            "hmacSalt": "xxxxxxxxxxxxxxxxxxxxxxx",
            "hmac": "xxxxxxxxxxxxxxxxxxxxxxx",
            "keywordId": "xxxxxxxxxxxxxxxxxxxxxxx",
            "supplierId": "xxxxxxxxxxxxxxxxxxxxxxx",
            
            // Price Beat information
            "priceBeat": {
                "clientPaidPrice": 19.99,
                "competitorPrice": 21.99,
                "clientOriginalPrice": 24.99,
                "competitorId": "competitor-123",
                "priceBeatTrigger": "automatic"
            }
        }
    ]
}

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

Example Usage (JavaScript)

Here's an example code snippet using JavaScript's Fetch API:

const url = 'https://<PA_END_POINT>/3.0/events/slot-impressions';
const accessToken = 'YOUR_ACCESS_TOKEN'; // Replace with your actual access token
const body = {
  customerId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  sessionId: 'xxxxxxxxxxxxxxxxxxxxxxx',
  events: [
    {
      currentUrl: "https://www.example.com/products/category",
      eventTime: "2024-03-01T14:00:00.000Z",
      refId: "product-123",
      widgetId: "xxxxxxxxxxxxxxxxxxxxxxx",
      routeId: "xxxxxxxxxxxxxxxxxxxxxxx",
      recommenderId: "xxxxxxxxxxxxxxxxxxxxxxx",
      campaignId: "xxxxxxxxxxxxxxxxxxxxxxx",
      tacticId: "xxxxxxxxxxxxxxxxxxxxxxx",
      personalized: true,
      
      // Retailer Boost event tracking
      retailBoostCollectionCampaignId: "xxxxxxxxxxxxxxxxxxxxxxx",
      
      // Retail Media event tracking
      adSetId: "xxxxxxxxxxxxxxxxxxxxxxx",
      adSetVersion: 1,
      costPerMille: 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('Slot Impression Recorded:', data))
  .catch(error => console.error('Error recording slot impression:', error));

Summary

This document provides details about the Slot Impression API, which is crucial for tracking user interactions with recommendation slots:

The API captures user impressions on product recommendation slots for analytics and performance measurement
The endpoint uses a POST method with URL https://<PA_END_POINT>/3.0/events/slot-impressions
Required parameters include customer ID, session ID, and impression details such as product reference ID and widget information
Additional parameters support retail media, retail boost, and price beat tracking
Special fields like personalized, bannerId, and placementId provide more context about the impression
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
JavaScript example demonstrates how to implement the API call in your application

API Endpoint​

Request Header​

Request Parameters (Body)​

Event Object Definition​

Retailer Boost Campaign​

Retail Media​

Price Beat Parameters​

Example Request Payload​

Response​

On Success​

On Error​

Example Usage (JavaScript)​

Summary​