Links

Algolia

Details an integration available for Algolia, built and maintained by Umbraco HQ.
This integration provides a custom dashboard and indexing component for managing search indices in Algolia.

Minimum version requirements

Umbraco CMS

Major
Minor/Patch
Version 10
10.3.1
Version 11
11.0.0

Authentication

The communication with Algolia is handled through their .NET API client, which requires an Application ID and an API key.
They are used to initialize the SearchClient which handles indexing and searching operations.

Configuration

The following configuration is required for working with the Algolia API:
appsettings.json
{
"Umbraco": {
"CMS": {
"Integrations": {
"Search": {
"Algolia": {
"Settings": {
"ApplicationId": "[your_application_id]",
"AdminApiKey": "[your_admin_api_key]",
"SearchApiKey": "[your_search_api_key]"
}
}
}
}
}
}
}
Algolia comes with a set of predefined API keys:
Name
Purpose
Search-Only API key
Public API key used on the front end for performing search queries.
Admin API key
Used in the Umbraco backoffice for create-, update- or delete operations on the indices.
More details on other use cases for the Algolia API keys can be found in the Algolia Docs.

Working with the integration

The following details how you can work with the Algolia integration.
  1. 1.
    Go to the Settings section in the Umbraco CMS backoffice.
  2. 2.
    Locate the Algolia Search Management dashboard.
In this view, you will be able to create definitions for indices in Algolia.
  1. 3.
    Provide a name for the index for each indices.
  2. 4.
    Select the Document Types to be indexed.
  3. 5.
    Select the fields you want to include for each Document Type.
After creating an index, only the content definition is saved into the algoliaIndices table in Umbraco, and an empty index is created in Algolia.
The actual content payload is pushed to Algolia for indices created in Umbraco in two scenarios:
From the dashboard, you can also perform a search over one selected index, or remove it.
Each Umbraco content item indexed in Algolia is referenced by the content entity's GUID Key field.

Algolia record structure

An indexed Algolia record matching an Umbraco content item contains a default set of properties. It is augmented by the list of properties defined within the Umbraco dashboard.
Properties that can vary by culture will have a record property correspondent with this naming convention: [property]-[culture].
The list of default properties consists of:
  • ObjectID - GUIDfrom the content item'sKey` property
  • Name - with culture variants if any
  • CreateDate
  • CreatorName
  • UpdateDate
  • WriterName
  • TemplateId
  • Level
  • Path
  • ContentTypeAlias
  • Url - with culture variants if any
  • Any registered properties on the Document Type

Extending the Algolia indexing

Indexing the content for Algolia is based on the IDataEditor.PropertyIndexValueFactory property from Umbraco CMS, the indexed value of the property being retrieved using the GetIndexValues method.
The ContentBuilder is responsible for creating the record object that will be pushed to Algolia and the AlgoliaSearchPropertyIndexValueFactory implementation of IAlgoliaSearchPropertyIndexValueFactory will return the property value.
The current implementation contains a custom converter for the Umbraco.MediaPicker3 property editor.
If a different implementation is required, you will need to follow these steps:
  1. 1.
    Inherit from AlgoliaSearchPropertyIndexValueFactory
  2. 2.
    Override the GetValue method
  3. 3.
    Add custom handlers to the Converters dictionary
  4. 4.
    Register your implementation in the composer
The following code sample demonstrates this approach:
public class ExtendedAlgoliaSearchPropertyIndexValueFactory : AlgoliaSearchPropertyIndexValueFactory
{
private readonly IMediaService _mediaService;
public ExtendedAlgoliaSearchPropertyIndexValueFactory(IDataTypeService dataTypeService, IMediaService mediaService)
: base(dataTypeService, mediaService)
{
_mediaService = mediaService;
Converters = new Dictionary<string, Func<KeyValuePair<string, IEnumerable<object>>, string>>
{
{ Core.Constants.PropertyEditors.Aliases.MediaPicker3, ExtendedMediaPickerConverter }
};
}
public override KeyValuePair<string, string> GetValue(IProperty property, string culture)
{
return base.GetValue(property, culture);
}
private string ExtendedMediaPickerConverter(KeyValuePair<string, IEnumerable<object>> indexValue)
{
return "my custom converter for media picker";
}
}

Extension registration

builder.Services.AddScoped<IAlgoliaSearchPropertyIndexValueFactory, ExtendedAlgoliaSearchPropertyIndexValueFactory>();