👁 Image
Ekom.Algolia 0.2.28

Ekom.Algolia

👁 Nuget
👁 Publish Ekom.Algolia

Algolia integration plugin for Ekom (Umbraco).

Features

• Product indexing with background queue/worker.
• Category indexing with background queue/worker.
• Product search service with Algolia SDK SearchForHits requests.
• Category search service with Algolia SDK SearchForHits requests.
• Algolia Insights events for view, add-to-cart, checkout, purchase.
• In-memory search result caching with store-scoped invalidation after reindex/update/delete.
• Index naming convention: {primary|replica|query_suggestions}.ENVIRONMENT.STORE.ENTITY[_sorted_by_{asc|desc}_ATTRIBUTE][.Locale][.Currency].

Install

Register services:

using Ekom.Algolia;

services.AddAlgolia();

Search products:

using Algolia.Search.Models.Search;
using Ekom.Algolia.Models.Search;
using Ekom.Algolia.Services;

public sealed class ProductSearchController
{
 private readonly IAlgoliaSearchService _algoliaSearchService;

 public ProductSearchController(IAlgoliaSearchService algoliaSearchService)
 {
 _algoliaSearchService = algoliaSearchService;
 }

 public async Task<IReadOnlyList<string>> SearchAsync(CancellationToken ct)
 {
 var response = await _algoliaSearchService.SearchProductsAsync(
 new AlgoliaSearchRequest
 {
 StoreAlias = "Store",
 Locale = "en-US",
 Currency = "USD",
 Query = new SearchForHits
 {
 Query = "shoe",
 HitsPerPage = 20,
 Filters = "Available:1"
 }
 },
 ct).ConfigureAwait(false);

 return response.Hits.Select(x => x.Title).ToList();
 }
}

Configuration (appsettings.json)

{
 "Ekom": {
 "Algolia": {
 "Enabled": true,
 "ApplicationId": "APP_ID",
 "AdminApiKey": "ADMIN_API_KEY",
 "SearchApiKey": "SEARCH_API_KEY",
 "InsightsApiKey": "INSIGHTS_API_KEY",
 "AnalyticsRegion": "eu",
 "Environment": "prod",
 "Indexing": {
 "Enabled": true,
 "Products": true,
 "Categories": true,
 "BatchSize": 1000,
 "ProductProperties": [
 "title",
 "summary",
 "description",
 "channels|array",
 "stockCount|int",
 "weight|decimal",
 "publishedAt|unix"
 ],
 "Dispatching": {
 "MaxBatchSize": 100,
 "FlushIntervalSeconds": 2,
 "MaxQueueSize": 10000,
 "MaxConcurrency": 2
 }
 },
 "Search": {
 "Enabled": true,
 "Products": true,
 "Categories": true,
 "QuerySuggestions": true,
 "IncludeUserToken": true,
 "VaryCacheByUserToken": false,
 "MinimumQueryLength": 2,
 "MaxHitsPerPage": 100,
 "QuerySuggestionsProvisioning": {
 "Enabled": true,
 "UseReplicas": false,
 "MinimumHits": 5,
 "MinimumLetters": 4,
 "EnablePersonalization": false,
 "AllowSpecialCharacters": false,
 "Exclude": []
 },
 "Cache": {
 "Enabled": true,
 "DurationMinutes": 60,
 "CacheEmptyResults": true
 }
 },
 "Events": {
 "Enabled": true,
 "ViewedProduct": true,
 "AddedToCart": true,
 "StartedCheckout": true,
 "Purchase": true
 },
 "Stores": [
 {
 "Alias": "Store"
 }
 ]
 }
 }
}

Settings reference

Notes

• Indexing triggers from Umbraco content notifications for ekmProduct and ekmCategory.
• Search uses the required SearchApiKey; indexing and settings operations continue to use AdminApiKey.
• When Search.QuerySuggestions is enabled, the plugin provisions the separate query_suggestions... index configuration automatically with the Admin API key.
• Set AnalyticsRegion to us or eu if you know your Algolia analytics region; if omitted, the plugin tries us and then eu.
• IAlgoliaSearchService.SearchProductsAsync(...) returns hits together with paging metadata, query text, processing time, and raw facets.
• IAlgoliaSearchService.SearchCategoriesAsync(...) searches a dedicated category index scoped by store alias and locale.
• The plugin always resolves and sets the Algolia index name from Ekom store alias, locale, and currency; callers should not set IndexName themselves.
• Category indexes omit the currency suffix because category records are scoped by store alias and locale only.
• Search cache keys include the resolved index name and serialized Algolia query payload so all SDK options affect caching.
• Search:IncludeUserToken sends user context to Algolia search. The default provider uses authenticated username, then session ID, then request trace identifier.
• Search:VaryCacheByUserToken controls whether that token also affects cache keys. Leave it false when results are not personalized so users can share cached results.
• Store Locale and Currency now come from the Ekom store resolved by alias, so appsettings.json only needs the store alias.
• Request and order context decide which culture and currency suffix is used; background indexing falls back to the store's default culture/currency.
• Title is always indexed as a top-level field, and NodeName contains the Umbraco node name.
• Available is indexed as 1 for available products and 0 for unavailable products, so it can be used for numeric ranking.
• Product records always include top-level ProductRanking and CategoryRanking integer fields. Both support negative values. ProductRanking reads the product ekmAlgoliaRank property and defaults to 0 when missing or invalid. CategoryRanking uses the highest valid ekmAlgoliaRank value across the product's categories and defaults to 0 when no category has a valid rank.
• Variants are not indexed by default.
• Indexing.ProductProperties supports one optional modifier per property: |array, |int, |decimal, |unix, or |unixms.
• Metafields can be indexed explicitly with metafield:<alias>, for example metafield:material, metafield:color|array, or metafield:releaseDate|unix.
• Multi-value metafields are skipped unless |array is configured.
• |array parses JSON arrays such as checkbox-list values like ["Web","Store"] into Algolia string arrays.
• |decimal accepts either comma or dot decimal separators, so values like 0,1 and 0.0 are indexed as decimals.
• Invalid |array, |int, and |decimal values are skipped instead of being indexed as strings.
• Manual reindex all endpoint: GET or POST /umbraco/backoffice/api/Ekom/AlgoliaBackoffice/RebuildIndexesAsync.
• Manual reindex store endpoint: GET or POST /umbraco/backoffice/api/Ekom/AlgoliaBackoffice/RebuildStoreIndexesAsync?storeAlias=Store.