Adding Banners

Creating a Query 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.

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.

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',
  condition: {
    pattern: 'harry potter',
    anchoring: 'contains'
  },
  consequence: {
    userData: {
      promo_content: '20% OFF on all Harry Potter books!'
    }
  }
}

index.save_rule(rule['objectID'], rule)

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

index.saveRule(rule, (err, content) => {
  if (err) throw err;
  console.log(content);
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
    'objectID': 'harry-potter-rule',
    'condition': {
        '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
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,
    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")
        .setCondition(condition)
        .setConsequence(consequence);

index.saveRule(rule);

1
2
3
4
5
6
7
8
9
10
11
rule := search.Rule{
  ObjectID:  "harry-potter-rule",
  Condition: 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",
  condition = 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.

• Go to your dashboard and select your index.
• Click the Query Rules tab.
• Click the New rule button.
• In the Condition section:
  • In the If the query… input field, set the anchoring to Contains.
  • Type “harry potter” in the input field and press Enter.
• In the Consequences section:
  • Click the Add consequence button and select Return Custom Data.
  • In the Custom JSON Data panel that shows up, add the data to return when the user query matches the rule: { "promo_content": "20% OFF on all Harry Potter books!" }
• Click Save.

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:

1
2
3
4
5
6
7
8
9
10
11
12
search.addWidget(
  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
<ais-query-rule-custom-data>
  <template slot="item" slot-scope="{ item }">
    <p>{{ item.promo_content }}</p>
  </template>
</ais-query-rule-custom-data>

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>

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 contextual Query Rules

If you want to apply contextual Query 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