Guides / Managing results / Rules / Merchandising

Jul 18, 2024

Adding banners

Click Create your first Rule or New rule and select Visual Editor.
In the It all starts here section, click Set query conditions.
In the Your query input, enter harry potter and click Apply.
In the What do you want to do? section, click Add Banner.
Enter the required content for your banner—the URL for your banner image and click Apply.
Review your banner preview now displayed above the hits.
Confirm your changes by clicking Review and Publish.

To add a rule with a banner consequence using the API, use the saveRule method. When adding a rule, you need to define a condition and a consequence. In the consequence, add search parameters and configure renderingContent using the following template:

Copy
{
  "renderingContent": {
    "widgets": {
      "banners": [
        {
          "image": {
            "urls": [
              "url": "https://www.algolia.com/banner.jpg"
            ]
            title: "20% OFF on all Harry Potter books!"
          },
          "link": {
            "url": "https://www.algolia.com/harry-potter-promo",
            "target": "_blank"
          }
        }
      ]
    }
  }
}

After adding the rule, you can display the banner in your UI if the renderingContent.widgets.banners property is present in the API response. You can use the Hits or InfiniteHits widgets from InstantSearch.js, React InstantSearch, or Vue InstantSearch to display the banner. The banner renders automatically unless you have configured the widget to hide it.

Copy

1
2
3
4
5
6
7
8
9
// Do not display the banner in the Hits widget
  search.addWidgets([
    instantsearch.widgets.hits({
      container: '#hits',
      templates: {
        banner: (_results) => null,
      },
    })
  ]);

Create a rule for returning custom data

If you want to motivate users to buy Harry Potter books, you could display a special promotion banner at the top of search results whenever their search query contains “harry potter”: “20% OFF on all Harry Potter books!”

For this, first need to set a rule that returns the custom data you want to display. Then, you need to display this data whenever it comes up.

You can add the rule using the API or the Algolia dashboard. Then, you can activate it in your frontend code to retrieve the banner.

Create a rule with the API

To add a rule, you need to use the saveRule method. When setting a rule, you need to define a condition and a consequence.

For the preceding example, you want to show the banner whenever the query contains “harry potter”. You don’t need it to be exact.

If the query is “harry potter azkaban” or “books harry potter”, you still want to display the promotion.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$rule = array(
  'objectID' => 'harry-potter-rule',
  'condition' => array(
    'pattern'   => 'harry potter',
    'anchoring' => 'contains',
  ),
  'consequence' => array(
    'userData' => array(
      'promo_content' => '20% OFF on all Harry Potter books!'
    )
  )
);

$response = $index->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
  objectID: 'harry-potter-rule',
  conditions: [{
    pattern: 'harry potter',
    anchoring: 'contains'
  }],
  consequence: {
    userData: {
      promo_content: '20% OFF on all Harry Potter books!'
    }
  }
}

index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const rule = {
  objectID: 'harry-potter-rule',
  conditions: [{
    pattern: 'harry potter',
    anchoring: 'contains'
  }],
  consequence: {
    userData: {
      promo_content: '20% OFF on all Harry Potter books!'
    }
  }
};

index.saveRule(rule).then(() => {
  // done
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
    'objectID': 'harry-potter-rule',
    'conditions': [{
        'pattern': 'harry potter',
        'anchoring': 'contains'
    }],
    'consequence': {
        'userData': {
            'promo_content': '20% OFF on all Harry Potter books!'
        }
    }
}

response = index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
let rule = Rule(objectID: "harry-potter-rule")
  .set(\.conditions, to: [
    Rule.Condition()
      .set(\.anchoring, to: .contains)
      .set(\.pattern, to: .literal("harry potter"))
  ])
  .set(\.consequence, to: Rule.Consequence()
        .set(\.userData, to: [
          "title": "20% OFF on all Harry Potter books!"
        ])
  )

index.saveRule(rule) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

1
2
3
4
5
6
7
8
9
10
val rules = rules {
    rule(
        "a-rule-id",
        Condition(Contains, Literal("harry potter")),
        Consequence(userData = json { "promo_content" to "20% OFF on all Harry Potter books!" }),
        enabled = false
    )
}

index.saveRules(rules)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
JObject data = new JObject();
data.Add("promo_content", "20% OFF on all Harry Potter books!");

var rule = new Rule
{
    ObjectID = "a-rule-id",
    Enabled = false,
    Conditions = new List<Condition> { new Condition { Anchoring = "contains", Pattern = "harry potter" } },
    Consequence = new Consequence
    {
        UserData = data
    }
  };

index.SaveRule(rule);

// Asynchronous
await index.SaveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
Map<String, Object> userData = new HashMap<>();
userData.put("promo_content", "20% OFF on all Harry Potter books!");

Condition condition = new Condition()
        .setPattern("harry potter")
        .setAnchoring("contains");
Consequence consequence = new Consequence()
        .setUserData(userData);

Rule rule = new Rule()
        .setObjectID("harry-potter-rule")
        .setConditions(Collections.singletonList(condition))
        .setConsequence(consequence);

index.saveRule(rule);

1
2
3
4
5
6
7
8
9
10
11
rule := search.Rule{
  ObjectID:  "harry-potter-rule",
  Conditions: []search.RuleCondition{{Anchoring: search.Contains, Pattern: "harry potter"}},
  Consequence: search.RuleConsequence{
    UserData: map[string]string{
      "promo_content": "20% OFF on all Harry Potter books!",
    },
  },
}

res, err := index.SaveRule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
val ruleToSave = Rule(
  objectID = "harry-potter-rule",
  conditions = Some(Seq(Condition(
    pattern = "harry potter",
    anchoring = "contains"
  ))),
  consequence = Consequence(
    userData = Some(Map("promo_content" -> "20% OFF on all Harry Potter books!"))
  ),
)

client.execute {
  save rule ruleToSave inIndex "index_name"
}

Create a rule in the dashboard

To add rules in the Algolia dashboard:

Go to the Algolia dashboard and select your Algolia application.
On the left sidebar, select Search.
Select your Algolia index:
Open the Rules page in the Algolia dashboard.
Select Create your first rule or New rule. In the drop-down menu, click the Manual Editor option.
In the Condition(s) section, keep Query toggled on, select Contains from the drop-down menu, and enter “harry potter” in the input field.
In the Consequence(s) section:
1. Click Add consequence and select Return Custom Data.
2. In the input field, add the data to return when a search query matches the rule: { "promo_content": "20% OFF on all Harry Potter books!" }
Save your changes.

Duplicate rules to adapt to user search patterns

To ensure that the Samsung Galaxy Note 20 Ultra banner displays for the search term “note” in the preceding example:

Duplicate the existing Samsung Galaxy Note 20 Ultra rule.
Edit the rule to change the Query search phrase to “Note”.

The newly duplicated rule now matches the first precedence logic criterion (Position) and displays the desired banner.

Now that your rule is ready, you can display a banner in your search UI if the userData property is present in the API response. For example, with InstantSearch:

Copy

1
2
3
4
5
6
7
8
9
search.addWidgets([
  instantsearch.widgets.queryRuleCustomData({
    container: '#banner',
    templates: {
      default: ({ items }, { html }) =>
        items.map(item => html`<p>${item.promo_content}</p>`),
    },
  })
]);

1
2
3
4
5
6
7
8
9
import { QueryRuleCustomData } from 'react-instantsearch-dom';

const Banner = (
  <QueryRuleCustomData>
    {({ items }) =>
      items.map(item => <p key={item.promo_content}>{item.promo_content}</p>)
    }
  </QueryRuleCustomData>
);

1
2
3
4
5
6
7
<ais-query-rule-custom-data>
  <ng-template let-items="items">
    <div *ngFor="let item of items">
      <p>{{ item.promo_content }}</p>
    </div>
  </ng-template>
</ais-query-rule-custom-data>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
struct Banner: Decodable {
  let title: String
}

class BannerViewController: UIViewController, ItemController {
  
  let titleLabel: UILabel = .init()
  
  override func viewDidLoad() {
    super.viewDidLoad()
    // some layout code
  }
  
  func setItem(_ item: Banner?) {
    titleLabel.text = item?.title
  }
  
}

func setupWidget() {
  let searcher = HitsSearcher(appID: "YourApplicationID",
                              apiKey: "YourSearchOnlyAPIKey",
                              indexName: "YourIndexName")
  let bannerViewController = BannerViewController()
  let queryRuleCustomDataConnector = QueryRuleCustomDataConnector<Banner>(searcher: searcher,
                                                                          controller: bannerViewController)

  searcher.search()
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@Serializable
data class Banner(val title: String)

class MyActivity: AppCompatActivity() {

  val searcher = HitsSearcher(
      applicationID = ApplicationID("YourApplicationID"),
      apiKey = APIKey("YourSearchOnlyAPIKey"),
      indexName = IndexName("YourIndexName")
  )
    val searchBox = SearchBoxConnector(searcher, searchMode = SearchMode.AsYouType)
    val queryRuleCustomData = QueryRuleCustomDataConnector<Banner>(searcher)
    val connection = ConnectionHandler(searchBox, queryRuleCustomData)

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val bannerView = TextView(this)
        queryRuleCustomData.subscribe { banner ->
            bannerView.text = banner?.title
        }
        
        searcher.searchAsync()
    }

    override fun onDestroy() {
        super.onDestroy()
        searcher.cancel()
        connection.clear()
    }
}

You can learn more about this widget in the InstantSearch API reference:

queryRuleCustomData for InstantSearch.js
<QueryRulesCustomData> for React InstantSearch
ais-query-rule-custom-data for Vue InstantSearch
ais-query-rule-custom-data for Angular InstantSearch

Apply rules with context conditions

If you want to apply rules based on context, see:

queryRuleContext for InstantSearch.js
<QueryRuleContext> for React InstantSearch
ais-query-rule-context for Vue InstantSearch
ais-query-rule-context for Angular InstantSearch

Determining priority when you have multiple banners

You may have quite a few semi-permanent promotional banners for specific product categories, as well as some time-limited, temporary banners for certain products.

For instance, an online IT hardware store has banners for the following categories:

Phones
Tablet computers
Laptop computers
Desktop computers

They also have 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

Since Algolia can only apply one rule at a time (and, hence, display one banner), tie-breaking precedence logic is used to determine which one to use.

Using the preceding example, users starts on the Phones page (and can see the appropriate banner for that), then search 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.

Don’t assume that a rule that was created some time ago will have a smaller objectID than a more recent rule. It’s best to not rely on objectID to determine precedence but to manually set it.

Did you find this page helpful?

Adding banners

On this page

Algolia out-of-the-box banner solution

Create a rule with a banner consequence in the Visual Editor

Create a rule with a banner consequence using the API

Display the banner with InstantSearch

Custom banner solution

Create a rule for returning custom data

Create a rule with the API

Create a rule in the dashboard

Duplicate rules to adapt to user search patterns

Retrieve the banner data in your UI

Apply rules with context conditions

Determining priority when you have multiple banners

On this page