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.
Package Links
Minimum version requirements
Umbraco CMS
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:
Algolia comes with a set of predefined API keys:
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.
Go to the Settings section in the Umbraco CMS backoffice.
Locate the Algolia Search Management dashboard.
In this view, you will be able to create definitions for indices in Algolia.
Provide a name for the index for each indices.
Select the Document Types to be indexed.
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 list of indices, the Build action is triggered, resulting in all content of specific Document Types being sent as JSON to Algolia.
Using a custom handler for CacheRefresher Notifications which will check the list of indices for the specific Document Type, and update a matching Algolia object. The handler will only run for SchedulingPublisher server or Single server roles.
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's
Key` propertyName
- with culture variants if anyCreateDate
CreatorName
UpdateDate
WriterName
TemplateId
Level
Path
ContentTypeAlias
Url
- with culture variants if anyAny 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 integration uses the same conversion process as Umbraco CMS uses for Examine, and apply a custom converter afterwards.
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.
To customize the returned value from Umbraco CMS you would need to use a custom converter specific to the particular indexed Umbraco property editor.
To extend the behavior, there are available options:
Version 2.3.0/3.1.0 and up
Starting with versions 2.3.0
and 3.1.0
, Algolia comes with geolocation support for records. This comes following a community request.
You can read more about enabling Algolia's geolocation for records in their official documentation.
By default the integration comes with a NULL
return value provider, but you can add your own by implementing the IAlgoliaGeolocationProvider
interface, and register it as singleton:
Version 2.1.5 and up
As a resolution for an issue that affects Umbraco.TinyMCE
property editor in Umbraco 13, the IProperty
object has been passed to the parse method of the converters.
A custom converter will look like this, allowing developers to add their implementation based on the content property:
Version 2.0.0 to 2.1.5
Starting with version 2.0.0, we provide a collection of converters for the following Umbraco property editors:
Umbraco.TrueFalse
Umbraco.Decimal
Umbraco.Integer
Umbraco.MediaPicker3
Umbraco.Tags
To create a new converter one should implement the IAlgoliaIndexValueConverter
interface. Then specify the name of the property editor and add the new implementation. The new converter will then need to be added to the Algolia Converters
collection.
To do so, follow these steps:
Create the new converter
Replace the default converter (if one exists) with the new one
Inject custom converters
Up to version 1.5.0
These implementations contain a custom converter for the Umbraco.MediaPicker3
property editor.
If a different implementation is required, you will need to follow these steps:
Inherit from
AlgoliaSearchPropertyIndexValueFactory
Override the
GetValue
methodAdd custom handlers to the
Converters
dictionaryRegister your implementation in the composer
The following code sample demonstrates this approach:
Extension registration
Last updated