Ad Data Source
Overview
The ad data source loads ad slot definitions from ads.json and makes them available as list items. Unlike the ad insertion property (which interleaves ads into another data source's results), this data source is used when a component is dedicated entirely to rendering ad slots — for example, a list of banner ads or a swiper of ad creatives.
When to use this
Use ad when a component's sole purpose is to display ads from ads.json. For inserting ads between content items in a mixed list, use the ad insertion property on the content data source instead.
For more details on ad insertion between content items, see: Embedded ads in Experienceemb
Basic Example
{
"type": "ad",
"contextKey": "banners",
"idPattern": "sidebar-banner"
}This loads all ad slot definitions from ads.json whose id matches the pattern sidebar-banner, and exposes them as $context.banners. A child component renders the ad creative using the slot's configuration.
Configuration
Type-specific properties
Property | Type | Default | Description |
|---|---|---|---|
idPattern | string | — | Optional regex pattern to filter ad slots by their id field. Only ads whose id matches the pattern are returned. If omitted, all ads are returned. |
Common configuration (inherited)
All common data source properties apply — contextKey, limit, etc.
For more details, see Data Sources Overviewdat
Advanced Features
Filtering by pattern
Use idPattern to restrict which ad slots are loaded. The value is a JavaScript regex pattern tested against each ad slot's id:
{
"type": "ad",
"contextKey": "banners",
"idPattern": "^sidebar-"
}This loads all ad slots whose id starts with sidebar- (e.g., sidebar-banner, sidebar-promo).
Conditional ad loading
The ad data source supports a condition value to enable or disable ad loading at runtime — for example, to suppress ads for subscribed users:
{
"type": "ad",
"contextKey": "promoAd",
"idPattern": "promo-banner",
"condition": {
"value": "$context.user.isSubscriber",
"operation": "EQUALS",
"compareValue": "false"
}
}For more details on conditions, see: TODO insert link to Conditions
Testing Notes / Edge Cases
- idPattern is a regex: The value is compiled with new RegExp(idPattern) and tested against each ad slot's id. An invalid regex logs a warning and falls back to returning all ad slots unfiltered.
- No idPattern returns all slots: If idPattern is omitted, the data source returns all ad slots defined in ads.json (subject to limit and element-level conditions).
- Ad vs. ad insertion: This data source is for ad-only components. Do not confuse it with the ad property on other data sources, which inserts ads between content items. Using both on the same component leads to duplicate ad slots.
- Condition-based suppression: When a data-source-level condition evaluates to false, the data source returns an empty list. Ensure the parent component handles the empty state without breaking the layout.
- Context-reactive filtering: The data source re-evaluates element-level conditions whenever the view context changes. If the filtered result differs, the component updates automatically.
- No SSR data: The ad data source does not restore data from SSR — it always fetches from the store on the client.