Integrating Banners

Match a campaign to a page

When creating a campaign to be triggered on a specific page, we will need to ensure the context of the campaign matches the query, background filter and/or filter parameters passed to the Search API request for the desired page.

• For example, if we were to create a campaign that should be triggered when a user searches for "Red Dress" we will set the campaigns context to match query with a value of Red Dress
• If we were to trigger a campaign on the "All Tops" page and the filter or background filter parameter that is used to filter the results by products with the field ss_category_hierarchy and a value of All Tops, then we will set the campaign's filter field context to match.

Once you have matched the campaign context to the context of the desired page and publish the campaign, we can now verify if the campaign is triggered by checking the merchandising.triggeredCampaigns object in the Search API response.

In the following example we are triggering a campaign for the "All Tops" page by matching the filter or background filter parameter for the field ss_category_hierarchy with a value of All Tops to the Search API request.

{
  "pagination": {...},
  "sorting": {...},
  "resultLayout": "grid",
  "results": [...],
  "facets": [...],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {...},
    "facets": [...],
    "facetsHide": [],
    "experiments": [],
    "variants": [],
    "personalized": false,
    "triggeredCampaigns": [
      {
        "id": "98908",
        "title": "All Tops",
        "type": "filter"
      }
    ]
  }
}

Locate banner content in the API response

Now that we have verified a campaign has been triggered, we can locate banner content. If banner content is configured we will find data returned within the merchandising.content object. Each banner will have it's own distinct key to signify the position of the banner on the page.

{
  "pagination": {...},
  "sorting": {...},
  "resultLayout": "grid",
  "results": [...],
  "facets": [...],
  "breadcrumbs": [],
  "filterSummary": [],
  "merchandising": {
    "redirect": "",
    "is_elevated": [],
    "elevated": [],
    "removed": [],
    "content": {
      "header": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Primary Banner</h1>\" type=\"text/widget\"></script><h1>Primary Banner</h1>"
      ],
      "banner": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Secondary Banner</h1>\" type=\"text/widget\"></script><h1>Secondary Banner</h1>"
      ],
      "footer": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Footer Banner</h1>\" type=\"text/widget\"></script><h1>Footer Banner</h1>"
      ],
      "left": [
        "<script data-banner-type=\"html\" data-banner-html=\"<h1>Left Banner</h1>\" type=\"text/widget\"></script><h1>Left Banner</h1>"
      ],
      "inline": [
        {
          "value": "<script data-banner-type=\"html\" data-banner-html=\"<h1>Inline Banner</h1>\" type=\"text/widget\"></script><h1>Inline Banner</h1>",
          "config": {
            "position": {
              "index": 2
            }
          }
        }
      ]
    },
    "facets": [...],
    "facetsHide": [],
    "experiments": [],
    "variants": [],
    "personalized": false,
    "triggeredCampaigns": [...]
  }
}

Integrating banner content

📘

Note Banner content is currently wrapped in a <script> tag due to a legacy feature. This <script> tag is not required and can be removed if desired. A future version of our API will remove this script tag.

Banners returned that are not inline banners are usually rendered as a full width banner on the page.

• header: Primary banner - rendered above results
• banner: Secondary banner - rendered above results below the Primary banner
• footer: Footer banner - rendered below results
• left: Left banner - intended to be rendered below filters that are oriented to the side of the results
• inline: Inline banner - rendered within the results of the page, will have the same dimensions of a product card.

📘

Note If inline banners are returned they will reduce the number of results returned to accomodate their positioning on the page

Inline banner content is found within the merchandising.content.inline as an array of objects. Each object will contain the banner content within the value key, and the position of the inline banner to be rendered within the results is returned within config.position.index.