Redirects in InstantSearch.js

Introduction

When you create specific landing pages to display search results, it’s handy to be able to redirect users to those dedicated pages, in the situation where the search query matches one of them.

In this tutorial, we’ll see two methods for setting up redirects in an Algolia index: using Rules and using dedicated indices.

Using Rules

The best way to set up redirects is through Rules. You can add redirect information as custom data to any Rule. The Rule returns this data when a search activates it. You also need to add a custom queryRuleCustomData widget that handles the Rule and redirects your user.

Configuring the Rule

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 the example below, we want to redirect whenever the query matches “star wars” exactly. If the query is “star wars lightsaber” or “books star wars”, we don’t want to redirect.

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
$rule = array(
  'objectID' => 'a-rule-id',
  'conditions' => array(array(
    'pattern' => 'star wars',
    'anchoring' => 'is'
  )),
  'consequence' => array(
    'userData' => array(
      'redirect' => 'https://www.google.com/#q=star+wars'
    )
  )
);

$index->saveRule($rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
  objectID: 'a-rule-id',
  conditions: [{
    pattern: 'star wars',
    anchoring: 'is'
  }],
  consequence: {
    userData: {
      redirect: 'https://www.google.com/#q=star+wars'
    }
  }
}

index.save_rule('a-rule-id', rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
const rule = {
  objectID: 'a-rule-id',
  conditions: [{
    pattern: 'star wars',
    anchoring: 'is'
  }],
  consequence: {
    userData: {
      redirect: 'https://www.google.com/#q=star+wars'
    }
  }
};

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
rule = {
  'objectID': 'a-rule-id',
  'conditions': [{
    'pattern': 'star wars',
    'anchoring': 'is'
  }],
  'consequence': {
    'userData': {
      'redirect': 'https://www.google.com/#q=star+wars'
    }
  }
}

response = index.save_rule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
let rule = Rule(objectID: "a-rule-id")
  .set(\.conditions, to: [
    .init(anchoring: .is, pattern: .literal("star wars"))
  ])
  .set(\.consequence, to: Rule.Consequence()
        .set(\.userData, to: ["redirect": "https://www.google.com/#q=star+wars"])
  )

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
@Serializable
data class Custom(val redirect: String)

val custom = Custom("https://www.google.com/#q=star+wars")
val myUserData = Json.encodeToJsonElement(Custom.serializer(), custom).jsonObject
// or
val myUserData = JsonObject(mapOf("redirect" to JsonPrimitive("https://www.google.com/#q=star+wars")))

val rule = Rule(
    objectID = ObjectID("a-rule-id"),
    conditions = listOf(
        Condition(anchoring = Anchoring.Is, pattern = Pattern.Literal("star wars"))
    ),
    consequence = Consequence(userData = myUserData)
)

index.saveRule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
JObject data = new JObject();
data.Add("redirect", "https://www.google.com/#q=star+wars");

var rule = new Rule
{
  ObjectID = "a-rule-id",
  Conditions = new List<Condition>
  {
    new Condition { Anchoring = "is", Pattern = "star wars" }
  },
  Consequence = new Consequence
  {
      UserData = data
  }
};

index.SaveRule(rule);

1
2
3
4
5
6
7
8
9
10
11
12
Condition condition = new Condition()
  .setPattern("star wars")
  .setAnchoring("is");
Consequence consequence = new Consequence()
  .setUserData(ImmutableMap.of("redirect", "https://www.google.com/#q=star+wars"));

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

index.saveRule(rule.getObjectID(), rule);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
rule := search.Rule{
    ObjectID:  "a-rule-id",
    Condition: []search.RuleCondition{
      {
        Anchoring: search.Is, Pattern: "star wars"
      },
    },
    Consequence: search.RuleConsequence{
        UserData: map[string]string{
            "redirect": "https://www.google.com/#q=star+wars",
        },
    },
}

res, err := index.SaveRule(rule)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
val ruleToSave = Rule(
  objectID = "a-rule-id",
  conditions = Some(Seq(Condition(
    pattern = "star wars",
    anchoring = "is"
  ))),
  consequence = Consequence(
    userData = Some(Map("redirect" -> "https://www.google.com/#q=star+wars"))
  ),
)

client.execute {
  save rule ruleToSave inIndex "index_name"
}

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.
Click the Rules tab.
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 Is in the dropdown and enter “star wars” 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: { "redirect": "https://www.google.com/#q=star+wars" }
Don’t forget to save your changes.

Now that everything is set up, you can use the queryRuleCustomData widget to update the page location anytime userData contains a redirect.

Copy
search.addWidgets([
  instantsearch.widgets.queryRuleCustomData({
    container,
    templates: {
      default: '',
    },
    transformItems(items) {
      const match = items.find(data => Boolean(data.redirect));
      if (match && match.redirect) {
        window.location.href = match.redirect;
      }
      return [];
    },
  })
]);

Using a dedicated index

An alternative way to set up redirects is to create a dedicated index with the list of redirects and the query terms that trigger them. This index is separate from your regular index, where your searchable records are. Whenever a user performs a search, you have to look in two indices: the regular one to search for items, and the redirect one that determines whether the user should be redirected.

This technique can be useful if you cannot use Rules or if you want access to typo tolerance, synonyms or filters.

Dataset

Copy
[
  {
    "url": "https://www.google.com/#q=star+wars",
    "query_terms": ["star wars"]
  },
  {
    "url": "https://www.google.com/#q=star+wars+actors",
    "query_terms": ["george lucas", "luke skywalker"]
  }
]

In this dataset, we give a list of URLs we want to redirect to. For each of them, we define a list of queries that we want to redirect from.

For example, the query “star wars” should redirect to https://www.google.com/#q=star+wars.

You can download the dataset on our GitHub. Have look at how to import it in Algolia here

Configuring the index

We want to redirect only if the query exactly matches one of the query_terms. We’re adding query_terms to our list of attributesForFaceting, so we can filter on it.

Copy

1
2
3
4
5
$index->setSettings([
  'attributesForFaceting' => [
    'query_terms'
  ]
]);

1
2
3
4
5
index.setSettings(Settings().set(\.attributesForFaceting, to: ["query_terms"])) { result in
  if case .success(let response) = result {
     print("Response: \(response)")
  }
}

Creating a custom search client

Now that everything is set up, you’ll create a custom search client that will simultaneously send requests to the regular and redirect indices.

The request to the redirect index is sent with:

an empty query, so we don’t filter with it
a filter on query_terms with the content of the current query, to match only on records that contains the current query exactly
hitsPerPage=1, as we only need the first record

Whenever we find hits in this index, we redirect:

Copy
const algoliaClient = algoliasearch(
  'YourApplicationID',
  'YourSearchOnlyAPIKey'
);

const customSearchClient = {
  ...algoliaClient,
  async search(requests) {
    if (requests[0].params.query) {
      const { results } = await algoliaClient.search([
        ...requests,
        {
          indexName: 'your_redirect_index_name',
          params: {
            hitsPerPage: 1,
            facetFilters: [`query_terms:${requests[0].params.query}`],
          },
        },
      ]);

      const redirect = results.pop();

      if (redirect.hits.length) {
        window.location.href = redirect.hits[0].url;
      }

      return { results };
    } else {
      return algoliaClient.search(requests);
    }
  },
};

const search = instantsearch({
  indexName: 'instant_search',
  searchClient: customSearchClient,
});