Using rules to customize search results by device

Example scenario

Suppose you work for a movie database company. Research shows that mobile users, unlike desktop users, tend to see a film in theaters after it has appeared in their search results. To capitalize on this, you partner with a movie theater chain and decide to promote newly released movies to your mobile users.

The records in your Algolia index include a release_date attribute, in Unix timestamp format, this is useful for identifying newly released movies.

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

By creating a mobile context and contextual rules, you can promote recent movies to mobile users.

Identify your user’s device

Before assigning a mobile context to searches, 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

You can assign context with InstantSearch or an Algolia API client.

Assign context with InstantSearch

Set the user’s device context at the beginning of their search session by adding 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 context as a search parameter whenever you search 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

You can create a mobile contextual rule with an API client or from the Algolia dashboard.

Create a contextual rule with an API client

Use the save-rule method to create a context-dependent rule. For example, to promote movies released after January 1, 2020, for mobile users:

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

Create a contextual rule with the dashboard

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 device

On this page

Example scenario

Identify your user’s device

Assign context

Assign context with InstantSearch

Assign context with an API client

Create a contextual rule

Create a contextual rule with an API client

Create a contextual rule with the dashboard

On this page