Guides / Managing results / Rules / Merchandising and promoting items

Adding Banners

On this page

Search isn’t only about retrieving results. Sometimes, depending on what the user searches for, you may want to display custom data in your UI, like ads or promotional banners.

For example, imagine you sell books online, and you have a special discount that you want to show people who are looking for Harry Potter books. By leveraging Algolia’s Rules, you can return custom data whenever a user sends a specific query, and use it to display a banner on your website.

Creating a Rule

Let’s say we want to motivate customers to buy Harry Potter books, by displaying a special promotion whenever their search query contains “harry potter”. On top of the search results, we want to display a banner that says “20% OFF on all Harry Potter books!”.

For this, we first need to set a Rule that returns the custom data we want to display. Then, we 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 front-end code to retrieve the banner.

Using 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.

In our case, we want to show the banner whenever the query contains “harry potter”. We don’t want it to be exact. If the query is “harry potter azkaban” or “books harry potter”, we 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);

Using the dashboard

You can also add your Rules in your Algolia dashboard.

  1. Select the Rules section from the left sidebar menu in the Algolia dashboard.
  2. Under the heading Rules, select the index you are adding a Rule to.
  3. Select Create your first rule or New rule. In the dropdown, click on the Manual Editor option.
  4. In the Condition(s) section, keep Query toggled on, select Contains in the dropdown, and enter “harry potter” in the input field.
  5. In the Consequence(s) section:
    • Click the Add consequence button and select Return Custom Data.
    • In the input field that appears, add the data to return when the user query matches the Rule: { "promo_content": "20% OFF on all Harry Potter books!" }
  6. Don’t forget to save your changes.

Retrieving the banner data in the Search UI

Now that your Rule is ready, you can add a banner in your search UI when the userData property is present in the API response. Here’s what it could look like with InstantSearch:

Copy 
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

@Serializable
data class Banner(val title: String)

class MyActivity: AppCompatActivity() {

    val searcher = SearcherSingleIndex(stubIndex)
    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:

Applying Rules with context conditions

If you want to apply Rules based on filters, have a look at:

Did you find this page helpful?