Resources Merchandising Actions

Setting up a Promotional Banner

How to set up promotional banners

Search isn’t only about retrieving results. Sometimes, depending on what the user searches for, you may want to display ads or promotional banners. This tutorial explains the process of setting up a Rule to trigger a banner image or a simple content.  

NOTE: This requires front end development work to be in place to trigger the banner image. Check with your development team for that to be in place and reference the docs.

From the Merchandising Studio homepage:

  • Click the Merch tools link at the bottom of the left-hand navigation.
    Merch Tools Access
  • Click “Rules” in the left-hand navigation.
    Rules access
  • Continue to Step 2 of the tutorial below.

  • Load dashboard section: Rules 
  • Select the correct index
  • Click on “New Rule” button and select “Manual Editor”
Manual Editor
  • In the Condition(s) section, keep Query toggled on, select Is/Contains/Starts with/Ends with in the dropdown, and enter a query that will trigger the consequence (e.g. “harry potter”) in the input field.
Create Rule
  • In the Consequence(s) section, click the Add consequence button and select Return Custom Data.
Return Custom Data
  • In the input field that appears, add the data to return when the user query matches the Rule in the following format:
    • { "promo_content": "___% OFF on all _____!" } if you want to display a content phrase
    • For example: { "promo_content": "20% OFF on all Harry Potter books!" } 
    • For example: { “description”: “Test”, “image”: { “desktop”: “/static/images/banners/cap-desktop.jpg”, “mobile”: “/static/images/banners/cap-mobile.jpg” },“title”: “Testing Title”} if you want to display an image
Custom Data
  • Optional: Add rule description for clarity and define a timeframe for the promotional campaign.
  • Review the rule before saving

Algolia can only apply one Rule at a time (and, hence, display one banner). In case of multiple applicable banners, the precedence logic, ranked by importance, is as follows:

  • Position: the earliest match wins (the match closest to the beginning of the query string).
  • Match length: the longest match wins; match length is determined by the number of words matched from the query string and the number of filters matched from the query parameters.
  • Anchoring: is > starts with > ends with > contains.
  • Context: a contextual Rule has higher priority than a general Rule or than a Rule using filters.
  • Filters: a Rule using filters has higher priority than a general Rule.
  • Literals over placeholders: if a word could match both a literal or a facet value, the literal takes precedence.
  • Temporary over permanent: if both a temporary and a permanent Rule match, the temporary Rule takes precedence.
  • Rule ID: if there are still conflicts after all other criteria have been applied, the smallest objectID in lexicographical order wins. This final criterion guarantees to break every tie. It most likely applies only when there are duplicate Rules.

How does lexicographic order work?

If two letters are the same case, then alphabetic order is used to compare them. If two strings contain the same characters in the same positions, then the shortest string comes first.


An online IT hardware store has permanent banners for the following categories:

  • Phones
  • Tablet computers
  • Laptop computers
  • Desktop computers.

The store also has temporary offers and associated banners for the phrases/products:

  • Huawei Honor Note 10
  • Xiaomi Redmi Note 10 Pro
  • Samsung Galaxy Note 20 Ultra
  • Samsung Galaxy Tab S7+
  • Samsung Galaxy Book Pro 360.

The user starts on the Phones page (and can see the appropriate banner for that), then searches for “note”. For most stages, Huawei Honor Note 10, Xiaomi Redmi Note 10 Pro, and Samsung Galaxy Note 20 Ultra are tied and take precedence over the category banners. The final tie-breaking stage, invoked in this case, is Rule ID: this looks for the Rule with the smallest objectID, which in this case just happens to be for the Huawei Honor Note 10.

Note: It is a better practice to set Rule Object ID manually. 

For example: { “objectID”: “harry-potter-rule” }

Multiple Banners

Merchandising Actions

Introducing the Merchandising Studio


Set up Keyword Redirects