Searching Content with Kentico Cloud: Algolia Integration
Search is an important part of websites as it helps your visitors find their desired content quickly. With Kentico Cloud, you can easily integrate external search engines so don’t need to implement a complicated search algorithm yourself.
In this blog post, I’m going to walk you through a sample integration of the Kentico Cloud headless CMS with Algolia. In fact, we implemented the Algolia search on the Kentico Cloud blog in September.
Getting Started with Algolia
The first step in the process is to create an account with Algolia. Once registered, you can log in and find the API keys in your profile. There are three basic pieces of information that you need to use when calling Algolia’s API:
- Application ID – to identify the application we want to work with
- Search-Only API Key – the API key usable for search queries (can be visible publicly so it can be used in the front end)
- Admin API Key – for managing indexes (needs to be kept private so it’s available in the back end only)
I would also recommend going through Algolia’s documentation to get familiar with Algolia’s concepts, API, and prepared UI widgets.
Now there are three basic steps to implementing the code:
- Index current data
- Ensure indexing when data changes (using a webhook)
- Search through the index and display results (when web visitors submit a query)
Index Current Data
Data should be indexed from the back end since indexing uses the private Admin API Key. We’ll use the Algolia.Search NuGet package, to ensure smooth working with Algolia’s API, and the Kentico Cloud Delivery .NET SDK, to acquire the blog post data from the Kentico Cloud app.
Firstly, we prepare a model called BlogPostSearchModel in which we store the data of the blog posts. The model needn’t only contain texts to be indexed, we can add various other data to the Algolia index for use later on in displaying results. By doing this, you can save time and don’t have to first obtain the data from the Kentico Cloud application. For our example, we’ll add the URLSlug field to be able to create links to blog posts.
Then we prepare the method for creating BlogPostSearchModel objects from data returned by the Delivery API as an object of the ContentItem type.
After that, we create a method that acquires all blog posts using the Delivery API and prepares a list of the BlogPostSearchModel instances leveraging the method above. We use ProjectID to identify the project from which to get blog posts.
This is a basic approach to acquiring data from Kentico Cloud, which I’ve chosen for demonstration purposes. For production code, I would suggest using a strongly typed models approach instead, as it is the recommended way of receiving content via the Delivery API.
We’ll also need a method that will sanitize the content of rich text fields, i.e. remove HTML tags and escape any special characters that might cause an error during indexing.
Now we can implement a method for indexing the given blog posts in Algolia’s index—to be used both for initial indexing and future data indexing.
Finally, we can leverage these methods to acquire our current blog posts and index them in Algolia.
Ensure Indexing When Data Changes
Kentico Cloud supports webhooks, which can notify your system whenever you publish new content or edit published content. To enable this, you need to set up a webhook as described in the documentation and implement an MVC action method that will handle the message from the webhook to the system.
This method will handle only HttpPost requests on the particular route specified in the “URL address” field in our webhook setting. (For example, if we use the “webhook” route, the URL should be “https://ourdomain/webhook”.) We should also check that the message wasn’t modified on its way. The signature, sent along with the message, contains a base64 encoded hash of the message. So, first you need to prepare a method that will compute the expected signature.
Then, we can implement the action method that will handle the webhook messages:
Search and Display Results
We’ll be performing a search on the front-end side so that we can then call Algolia’s servers and receive a response directly without calling back to our servers. This approach should ensure much better performance. We can also leverage existing Algolia widgets for easier implementation of the UI. So how will we build our UI?
First of all, we need to prepare an input field into which users can enter their search queries. Then we can add some divs that will act as containers for other UI parts like statistics (how many results were found), pager, and (mainly) search results.
The layout of the particular item in results is defined by a template. The template consists of HTML code placed within the <script> tag (so it’s not rendered to a page) with an ID “hit-template”. There are two types of variables that can be used in the template which Algolia’s script automatically resolves:
- Variable within two pairs of curly brackets—these are properties from the index.
- Variable within three pairs of curly brackets—where we reference the _highlightResult object which contains properties from the index, with HTML highlights on the matched words.
In this walkthrough, I’ve showed you how easily you can integrate Kentico Cloud with Algolia to enable searching of your website content. This functionality will help improve user experience.
Are you going to give Algolia search a try?
Have you already checked out the search on the Kentico Cloud blog? What do you think?
Let us know in the forum below!