Guides / Managing results / Rules / Merchandising and promoting items

Oct. 13, 2021

Adding Banners

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);

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
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"
}

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)

Using the dashboard

You can also add your Rules in your Algolia dashboard.

Select the Search product icon on your dashboard and then select your index.
Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index you are adding a Rule to.
Select Create your first rule or New rule. In the dropdown, click on the Manual Editor option.
In the Condition(s) section, keep Query toggled on, select Contains in the dropdown, and enter “harry potter” in the input field.
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!" }
Don’t forget to save your changes.

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

There are no guarantees on the format and numbering of objectID, so 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.

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 will now match the first precedence logic criterion (Position) and display the desired banner.

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
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()
    }
}

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

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()
}

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

queryRuleCustomData for InstantSearch.js
QueryRuleCustomData for React InstantSearch
ais-query-rule-custom-data for Vue InstantSearch
ais-query-rule-custom-data for Angular InstantSearch

Applying Rules with context conditions

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

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

Did you find this page helpful?