Skip to content

Storefront changes

Beta feature

Retail Media features are currently in closed beta. Contact Voyado if you want to take part in the program.

To support sponsored products in the storefornt, the following is needed:

  • Implement sponsored list requests (if used)
  • Send impression events when sponsored products are viewed
  • Make sponsored products visually distinct
  • Ensure correct metadata is included in requests

Sponsored lists are optional recommendation lists that contain only sponsored products. They are similar to standard recommendation lists, but have their own ID and are tied to a specific page.

Unlike recommendation lists that are returned by a landing page request, sponsored lists are retrieved separately using the sponsored page endpoint.

Key differences from landing page requests:

  • The sponsored page endpoint returns only sponsored lists and banners.
  • The endpoint should be called once per page visit, not repeatedly.
  • Sponsored responses may be slightly slower due to the real-time bidding process.

Recommendation: Call the sponsored page endpoint in parallel with your landing page request to avoid delaying page rendering.

Sponsored lists may return empty responses if no suppliers bid for that slot. Treat them as optional content and design gracefully for fallback scenarios.

A note on Performance

Due to the real-time bidding step, sponsored lists will naturally be slightly slower to respond than normal recommendation lists. It is recommended to make the sponsored page call in parallel with the landing page request.

Empty results

Sponsored page queries may return empty responses at any time (e.g., if no supplier bids for a banner or list). Always treat banners and sponsored lists as optional content and design your storefront so it gracefully handles cases when no banners are returned.

Banners are requested using the sponsored page endpoint. To enable banner support in the storefront, implement the following:

  • Requests: Request banners & lists using the sponsored page endpoint when loading the page. See Key differences from landing page requests above for further guidance.
  • Impression tracking: When a banner image becomes visible to a visitor, send an impression notification containing the banner image’s ticket.
  • Click tracking: When a banner is clicked, send the click notifications with the banner image’s ticket.
  • Redirects: On click, redirect the visitor to the URL defined in the banner image´s link field.
  • Ensure correct metadata is included in requests

Distinguishing sponsored resources

Although Voyado does not require it, you may need to clearly label sponsored content to comply with local advertising or consumer protection regulations.

To support this, sponsored products have the field sponsored set to true, allowing you to make them visually distinct.

Impression tracking

Whenever sponsored resources become visible to storefront visitors, impression notifications must be triggered. This is done by firing an impression notification. Impression notifications must be sent when the following resources are seen by a visitor:

  • Sponsored lists. The list will have a field impressionTicket, which should be included in the notification.
  • Primary lists with sponsored product. Send an impression notification when the first sponsored product is seen, using the product´s ticket. Only one impression notification is required for the primary list!
  • Banners. Send an impression notification whenever a banner image is rendered into view, using the ticket field of the image.

When to send notifications

The general guideline is to send a notification when 50% of the sponsored area has been on screen for at least a second, but there are no hard rules regarding this and is up to you how you wish to implement it.

Refreshing the page or filtering the product selection might cause sponsored segments to change. In this case you may send a new impression notification, though this is not required.

Metadata

In order to identify non-human traffic, it is important to add valid request headers in the call to Elevate. The headers needed are:

  • User-Agent: with the user agent of the storefront visitior.
  • X-Forwarded-For: with the IP address of the storefront visitor.

Without valid values in the request headers, sponsored content will not be served.

×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE