Define advertisers in the catalog

Defining advertisers within your catalog is a crucial step when implementing Sponsored Listing.

You will need to send a separate metadata field with every item that Constructor can use as an advertiser identifier. We do not recommend using existing metadata such as brand, seller, or publisher if they do not meet the requirements listed below.

When creating this advertiser metadata field, please ensure it meets the following requirements:

• Always present: The advertiser field should always be included in an item record.
• Consistent name: The advertiser field name should be the same across all indexes, meaning it is the same across all catalog files. This is particularly important if you plan to run promotions in multiple regions.
• Clear values: Filed values should clearly represent an advertiser (e.g., brand name, advertiser name, etc.).
• Stable values: Once assigned to an item, advertiser values should not change. Each value acts as a unique identifier for an advertiser; if it changes, Constructor will treat it as a new advertiser.

Response format

If you are live with Sponsored Listings, then Constructor will include sponsored labels as part of a search or browse API response. If a result set includes sponsored items, then the API response will include the is_retail_media: true flag for those items. Deciding how sponsored labels will display on a results page is the responsibility of your team.

The response format for a sponsored item is as follows:

{
  "results": [{
    // ...
    "labels": {
      "is_retail_media": true,
      "sl_campaign_id": "349eaf16-d1a0-48ab-a4d8-343a05553778",
      "sl_campaign_owner": "Advertiser Name"
    }
  }]
}

Responses, like the one above, can also include the following labels:

• sl_campaign_id: The ID of the campaign from which the product came. It is optional, depending on the provider of the sponsored items.
• sl_campaign_owner: Indicates the advertiser that promoted this product. It is optional, depending on the provider of the sponsored items.

Event tracking for sponsored items

Event tracking for sponsored items will depend on what platform is providing the item—Constructor or a third-party Retail Media platform.

Tracking for a sponsored item from Constructor

For Constructor’s beacon to track events for sponsored items, you must expose the campaign id (sl_campaign_id) and the advertiser (sl_campaign_owner) in your site’s HTML code.

When rendering a search and browse results set, add the data-cnstrc-sl-campaign-id and data-cnstrc-sl-campaign-owner properties to each DOM element representing one item using the data provided in labels as described above.

Learn more about tracking via HTML attributes in our data-driven event tracking documentation.

Tracking for media from a third-party retail media platform

If you’re using a third-party Retail Media platform through Constructor’s Mediation Layer, you will receive a set of properties that the provider uses for tracking in labels. The exact set of properties depends on the provider, but they are prefixed with dsp_. You can then implement tracking with the provider by exposing or sending this data to them as you would if you were integrating with them directly.

Alternatively, you can let Constructor do the work. If you use our beacon for tracking, then we can forward our tracking data to your provider. Please note that provider-specific limitations may exist, and an exact plan will be discussed during implementation.

Mobile event tracking

Mobile event tracking is essential for sponsored campaigns. By recording shopper interactions on mobile apps and storefronts, you can ensure proper attribution and accurate reporting.

Learn how to track search and browse events for iOS and Android below:

• iOS
  • Track search events
  • Track browse events
• Android
  • Track search events
  • Track browse events

Displaying sponsored labels

Your team is responsible for designing and rendering the “sponsored” badge for related items on a search results or browse category page. Your region may have legal requirements for how these items are labeled, so please defer to those requirements.

In general, we recommend labeling sponsored products subtly, with text as Sponsored or Featured.

Below are results pages from different companies that show how those companies have chosen to label sponsored items.