Skip to main content
Recommender Ads surface relevant products to users based on their current context — typically on product detail pages (recommending similar products to the one being viewed) or on category and destination landing pages. They can be displayed within an existing “Similar Deals” container, or as a new standalone carousel.
Before going live with Recommender Ads, you must supply Platform 195 with a destination/category ID mapping and a product ID list. See Setup requirements.

​
Setup requirements

To configure Recommender Ads, Platform 195 requires:
  • Destination or category ID mapping — a CSV or feed of all destinations/categories with their associated IDs, preferably at two levels (e.g. Country, Region, Resort).
  • Product IDs — a CSV or feed of all product IDs available on your site.

​
Requesting recommender ads

POST to the recommender ad endpoint at page load. Authentication is required via headers — see Authentication. Endpoint: POST https://dev.api.upliftads.io/v3/recommender-ad 
{
  "siteId": YOUR_SITE_ID,
  "zoneIds": [YOUR_ZONE_ID],
  "count": 5,
  "keywords": [
    "Dest.{DestinationMacro}",
    "Dep.{DepartureMacro}",
    "MonthYear.{DateMacro}",
    "Adults.{AdultsMacro}",
    "Children.{ChildrenMacro}",
    "Star.{StarRatingMacro}",
    "ID.{ProductIDMacro}"
  ]
}

​
Request parameters

ParameterTypeRequiredDescription
siteIdnumberYesYour site ID. Provided by Platform 195. Must match the x-site-id header.
zoneIdsarrayYesZone ID for the recommender placement. Provided by Platform 195.
countnumberYesNumber of product candidates to request.
keywordsarrayNoTargeting parameters reflecting the user’s current context. See keyword targeting.

​
Keyword targeting

Keywords for Recommender Ads reflect both the user’s search context and the specific product page they are viewing.
Targeting keyDescriptionExample valueKeyword format
DestDestination ID. Format: {ID}-{Level} where level is 1 = Country, 2 = Region, 3 = Resort.MadeiraDest.123-2
DepDeparture airport codeLondon GatwickDep.LGW
MonthYearTravel month and year in MMYYYY formatApril 2023MonthYear.042023
DurationNumber of nights searched7Duration.7
AdultsNumber of adults2Adults.2
ChildrenPass Y if the search includes children1 childChildren.Y
StarStar rating of the product currently being viewed5Star.5
IDProduct ID of the product currently being viewedPTMD0020ID.PTMD0020

​
Serving recommender ads

The response returns a ranked list of product candidates in priority order.

​
Back-end

The response contains productID values. You must merge these against your existing product feed to retrieve the content needed to render each card (image, name, price, deeplink, etc.). If no product feed exists, Platform 195 can serve static content instead.

​
Front-end

Nested within an existing container: Place the Uplift-returned products into the pre-agreed positions within your existing recommended products container. Label each as Ad or Sponsored. Standalone carousel: If this is a new container, present products as side-by-side cards using reduced design elements from your search listings. Make it clear to users that the products are ads — for example, Sponsored hotels we think you'll like.

​
Handling empty responses

If the response is empty (no relevant products found):
  • Standalone container — collapse the div so no blank space appears.
  • Nested container — backfill any reserved ad positions with other products from your feed.
  • Partial response — backfill remaining positions from your feed if fewer products are returned than available slots.

​
Response

{
  "decisions": {
    "Recommender_1": [
      {
        "adId": 000000000,
        "productID": "YOUR_PRODUCT_ID",
        "campaignId": 000000000,
        "creativeId": 000000000,
        "flightId": 000000000,
        "impressionUrl": "https://dev.engine.upliftads.io/i.gif?e=...",
        "viewableImpressionUrl": "https://dev.engine.upliftads.io/e.gif?e=...",
        "conversionUrl": "https://dev.engine.upliftads.io/e.gif?e=...",
        "clickUrl": "https://dev.engine.upliftads.io/r?e=..."
      }
    ]
  }
}

​
Reporting

See Tracking Ad Engagement for full details on firing impression, click, viewable impression, and conversion tracking URLs.

​
Evidencing

Wrap each recommender ad placement in a div with a class of FID_ followed by the flightId from the response: 
<div class="existing_class FID_{{flightId}}">
  <!-- recommender ad HTML -->
</div>