Using rules to customize search results by platform

What’s a context

A context is a string passed as a search parameter to InstantSearch or an Algolia API client.

Identifying your user’s device

Before you can assign a mobile context to searches, you must identify your user’s device. To do this, write a function that detects what device the app is running on, and return “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 a mobile or desktop device
  return isMobile ? 'mobile' : 'desktop';
};

Assign context with InstantSearch

To set the user’s device at the beginning of their search session, 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],
});

1
2
3
4
5
let platform = getPlatform()

let searcher = HitsSearcher(appId: "YourAppId", apiKey: "YourAPIKey", indexName: "YourIndexName")

searcher.request.query.ruleContexts = [platform]

Assign context with an API client

Pass the user’s device 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);
});

Create a contextual rule

After you’ve implemented and tested your app with the mobile context, you can create a mobile rule (with an API client or from the dashboard).

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. This isn’t the case for desktop users.

You set up a partnership with a movie theater chain, and decide to promote 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 example record, the release_date attribute is a Unix timestamp, which makes it suitable for sorting and filtering.

With an API client

Create a context-dependent rule using the save-rule method. Continuing with the example, 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
val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    conditions = listOf(Condition(
        context = "mobile"
    )),
    consequence = Consequence(
        query = Query(filters = "release_date >= 1577836800")
    ),
)

movies.saveRule(rule)

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

With the dashboard

With the dashboard, create a rule as follows:

Select the Search product icon on your dashboard.
Select the Rules section from the left sidebar menu in the Algolia dashboard.
Under the heading Rules, select the index to which you’re adding a rule.
Select Create your first rule or New rule. In the drop-down menu, click 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, add a filter for the release_date attribute. For example, to show all movies released since 2020 (1577836800 is the Unix timestamp for January 1, 2020), enter: { "filters": "release_date >= 1577836800" }
If you wish, you can add other consequences by clicking Add consequence. For example, there may be movies that you want to pin to a specific location or rank at the top,
Save your changes.

Did you find this page helpful?

Using rules to customize search results by platform

On this page

What’s a context

Identifying your user’s device

Assign context with InstantSearch

Assign context with an API client

Create a contextual rule

With an API client

With the dashboard

On this page