Guides / Managing results / Rules / Rules Overview

Nov. 10, 2020

Using Rules to Customize Search Results By Platform

What is a context

A context is a string passed as a search parameter. In this tutorial, we illustrate two ways of creating a mobile context: with InstantSearch and with the API clients.

Identifying your user’s device

Before assigning a mobile context to searches, you need to identify your user’s device. We can write a function that detects what device it’s running on, and returns “desktop” or “mobile” depending on what it finds:

Copy

1
2
3
4
5
const getPlatform = () => {
  const isMobile = ...
  // your logic to determine whether a user is on mobile or desktop
  return isMobile ? 'mobile' : 'desktop';
};

Fetching your user’s device makes more sense on the front end, which is why there are no back-end snippets.

Assigning a context to a search

With InstantSearch

To set the user’s device at the beginning of their search session, you can add it to the searchParameters setting of your InstantSearch instance during initialization.

Copy

1
2
3
4
5
const platformTag = getPlatform();

instantsearch.widgets.configure({
  ruleContexts: [platformTag],
});

With an API client

You can also pass the user’s device using the API clients, by providing it as a search parameter whenever you call search on your index.

Copy

1
2
3
4
5
6
7
8
9
const index = client.initIndex('movies');

const platformTag = getPlatform();

index.search('query', {
  ruleContexts: platformTag
}).then(({ hits }) => {
  console.log(hits);
});

Creating Contextual Rules

After you’ve implemented and tested your app with the mobile context, you can create your mobile rule.

Suppose that you are a movie database company. After some research, you realize that mobile users often go see a film in theaters if it shows up in their search results, which is not the case for desktop users.

You set up a partnership with a movie theater chain, and decide to promote recently released movies to your mobile users. The records in your Algolia index have the following attributes:

Copy
{
  "title": "Fargo",
  "year": 1996,
  "director": "Joel Coen",
  "release_date": 841795200,
  "rating": 93
}

In the record above, the release_date attribute is a Unix timestamp, which makes it suitable for sorting and filtering.

Using the API

You can create a context-dependent Rule using the save-rule method of any of our API clients. Continuing on the example above, you would call save-rule with the following parameters:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
$rule = array(
    'objectID' => 'a-rule-id',
    'conditions' => array(array(
        'context' => 'mobile',
    )),
    'consequence' => array(
        'params' => array(
            'filters' => 'release_date >= 1577836800',
        )
    )
);

$movies->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
rule = {
  objectID: 'a-rule-id',
  conditions: [
    { context: 'mobile' }
  ],
  consequence: {
    params: {
      filters: 'release_date >= 1577836800'
    }
  }
}

movies.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
const rule = {
  objectID: 'a-rule-id',
  conditions: [{
    context: 'mobile'
  }],
  consequence: {
    params: {
      filters: 'release_date >= 1577836800'
    }
  }
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
rule = {
    'objectID': 'a-rule-id',
    'conditions': [{
        'context': 'mobile'
    }],
    'consequence': {
        'params': {
            'filters': 'release_date >= 1577836800'
        }
    }
}

response = movies.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
let modifiedQuery = Query().set(\.filters, to: "release_date >= 1577836800")

let rule = Rule(objectID: "a-rule-id")
  .set(\.conditions, to: [Rule.Condition().set(\.context, to: "mobile")])
  .set(\.consequence, to: Rule.Consequence().set(\.query, to: modifiedQuery))

movies.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
19
20
Rule ruleToSave = new Rule
{
    ObjectID = "a-rule-id",
    Conditions = new List<Condition>
    {
      new Condition { Context = "mobile"  }
    },
    Consequence = new Consequence
    {
        Params = new ConsequenceParams
        {
            AutomaticFacetFilters = new List<AutomaticFacetFilter>
            {
                new AutomaticFacetFilter { Facet = "release_date >= 1577836800" }
            }
        }
    }
  };

movies.SaveRule(rule, forwardToReplicas: false);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
Condition condition = new Condition()
    .setContext("smartphone");

ConsequenceParams params = new ConsequenceParams()
    .setFilters("release_date >= 1577836800");

Consequence consequence = new Consequence()
    .setParams(params);

Rule rule =
    new Rule()
        .setObjectID("a-unique-identifier")
        .setConditions(Collections.singletonList(condition))
        .setConsequence(consequence);

movies.saveRule(rule);

// Asynchronous
movies.saveRuleAsync(rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
forwardToReplicas := opt.ForwardToReplicas(false)

rule := search.Rule{
  ObjectID:  "a-rule-id",
  Conditions: []search.RuleCondition{{Context: "mobile"}},
  Consequence: search.RuleConsequence{
    Params: &search.RuleParams{
      QueryParams: search.QueryParams{
        Filters: opt.Filters("release_date >= 1577836800"),
      },
    },
  },
}

res, err := movies.SaveRule(rule, forwardToReplicas)

1
2
3
4
5
6
7
8
9
10
11
12
val ruleToSave = Rule(
  objectID = "a-rule-id",
  conditions = Some(Seq(Condition(
    context = "mobile",
  ))),
  consequence = Consequence(
    params = Some(Map("filters" -> "release_date >=  1577836800")),
  ),
)
client.execute {
  save rule ruleToSave inIndex "movies"
}

1
2
3
4
5
6
7
8
9
10
11
val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    conditions = listOf(Condition(
        context = "mobile"
    )),
    consequence = Consequence(
        query = Query(filters = "release_date >= 1577836800")
    ),
)

movies.saveRule(rule)

Using the dashboard

With the dashboard, you can test and create Rules. Follow the steps below:

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, toggle Context on and toggle Query off.
Enter “mobile” in the context input field.
In the Consequence(s) sections, click Add Consequence, and select the Add Query Parameter consequence.
In the editor that appears, add a filter for the release_date attribute. In the following example, we filter all movies with a release date in 2020 (1577836800 is the Unix timestamp for January 1st, 2020).
Copy
1 2 3 { "filters": "release_date >= 1577836800" }
If there are films that you want to pin to a specific location, or rank at the top, you can add other consequences by clicking Add consequence.
Don’t forget to save your changes.

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

Building Search UI

PHP

Ruby

JavaScript

Python

Swift

Kotlin

Android

.NET

Java

Golang

Scala

InstantSearch.js

React InstantSearch

Vue InstantSearch

Angular InstantSearch

InstantSearch iOS

InstantSearch Android

Autocomplete

Crawler Configuration API

Index settings and search parameters

A full reference of API Endpoints

Rails

Symfony

Django

Laravel

Crawler

Magento 2

WordPress

Shopify

Salesforce Commerce Cloud B2C

Netlify

Using Rules to Customize Search Results By Platform

On this page

What is a context

Identifying your user’s device

Assigning a context to a search

With InstantSearch

With an API client

Creating Contextual Rules

Using the API

Using the dashboard

Did you find this page helpful?

On this page