Ekom.Algolia 0.2.35

Ekom.Algolia

Algolia integration plugin for Ekom (Umbraco).

Features

• Product indexing with background queue/worker.
• Category indexing with background queue/worker.
• Standard Umbraco content indexing with background queue/worker.
• Product search service with Algolia SDK SearchForHits requests.
• Category search service with Algolia SDK SearchForHits requests.
• Standard content search and federated multi-index search.
• 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,
        "Variants": false,
        "BatchSize": 1000,
        "ProductProperties": [
          "title",
          "summary",
          "description",
          "channels|array",
          "stockCount|int",
          "weight|decimal",
          "publishedAt|unix"
        ],
        "Dispatching": {
          "MaxBatchSize": 100,
          "FlushIntervalSeconds": 2,
          "MaxQueueSize": 10000,
          "MaxConcurrency": 2
        }
      },
      "ContentIndexing": {
        "Enabled": true,
        "EnforcePublisherOnly": true,
        "BatchSize": 1000,
        "Indexes": [
          {
            "IndexName": "SearchIndex",
            "ContentTypes": [
              {
                "Alias": "article",
                "Properties": [
                  "title",
                  "summary",
                  "publishedAt|unix"
                ]
              }
            ]
          }
        ]
      },
      "Search": {
        "Enabled": true,
        "Products": true,
        "Categories": true,
        "GroupVariantsByProduct": 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

Usage notes

Indexing triggers and API keys

Product and category indexing is triggered from Umbraco content notifications for ekmProduct and ekmCategory.

Search requests use SearchApiKey. Indexing, settings updates, replicas, delete operations, and query suggestion provisioning use AdminApiKey.

{
  "Ekom": {
    "Algolia": {
      "ApplicationId": "APP_ID",
      "AdminApiKey": "ADMIN_API_KEY",
      "SearchApiKey": "SEARCH_API_KEY"
    }
  }
}

When Search:QuerySuggestions is enabled, the plugin provisions the separate query_suggestions... index configuration automatically. Set AnalyticsRegion to us or eu if you know it; if omitted, the plugin tries us and then eu.

{
  "Ekom": {
    "Algolia": {
      "AnalyticsRegion": "eu",
      "Search": {
        "QuerySuggestions": true
      }
    }
  }
}

Index naming and store context

The plugin resolves Algolia index names from the configured environment, store alias, locale, and currency. Callers should not set SearchForHits.IndexName; the search service sets it before executing the request.

Product index names include currency when a currency is resolved:

primary.prod.Store.products.en-US.USD

Category index names omit currency because category records are scoped by store alias and locale only:

primary.prod.Store.categories.en-US

Standard content index names resolve as {IndexName}.{Environment}.{Culture}:

SearchIndex.prod.en-US

Only the store alias must be configured in appsettings.json. Locale and currency are resolved from the Ekom store and the current request/order context. Background indexing falls back to the store's default culture and currency.

{
  "Ekom": {
    "Algolia": {
      "Stores": [
        {
          "Alias": "Store"
        }
      ]
    }
  }
}

Searching

IAlgoliaSearchService.SearchProductsAsync(...) returns typed product hits with paging metadata, query text, processing time, and raw facets.

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);

Other search methods target their own index types:

• SearchCategoriesAsync(...) searches category records scoped by store alias and locale.
• SearchContentAsync(...) searches configured standard content indexes.
• FederatedSearchAsync(...) executes products, categories, query suggestions, and content searches in one Algolia multi-search request.

Search caching and user tokens

Search cache keys include the resolved index name and serialized Algolia query payload, so SDK options such as filters, facets, page, and hits-per-page affect caching.

Search:IncludeUserToken sends user context to Algolia. The default provider uses authenticated username first, then session ID, then request trace identifier.

Search:VaryCacheByUserToken controls whether that token also affects cache keys. Leave it false for shared cache when results are not personalized. Set it to true when Algolia personalization changes result order or content per user.

{
  "Ekom": {
    "Algolia": {
      "Search": {
        "IncludeUserToken": true,
        "VaryCacheByUserToken": false,
        "Cache": {
          "Enabled": true,
          "DurationMinutes": 60
        }
      }
    }
  }
}

Product records and ranking fields

Product records always include Title as a top-level field. NodeName contains the Umbraco node name.

Available is indexed as a numeric value so it can be used for ranking:

{
  "Title": "Running shoe",
  "NodeName": "Running shoe - black",
  "Available": 1
}

Product records also include 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.

{
  "ProductRanking": 10,
  "CategoryRanking": 5
}

Variant indexing

Variants are not indexed by default. Enable variant indexing when products use placeholder parent SKUs and the real sellable SKUs live on variants.

{
  "Ekom": {
    "Algolia": {
      "Indexing": {
        "Variants": true
      },
      "Search": {
        "GroupVariantsByProduct": true
      }
    }
  }
}

When enabled, the plugin creates one additional product record per variant. Variant records use the variant SKU as top-level Sku, preserve the parent product SKU as ParentSku, and include ProductId and VariantId for grouping and selection.

{
  "objectID": "product-key_variant-key",
  "ProductId": "product-key",
  "VariantId": "variant-key",
  "Sku": "REAL-VARIANT-SKU",
  "ParentSku": "PLACEHOLDER-SKU",
  "IsVariant": true,
  "variantSku": "REAL-VARIANT-SKU",
  "variantTitle": "Black / XL"
}

Product indexes are configured with AttributeForDistinct = ProductId. Search:GroupVariantsByProduct defaults to true, so normal searches return grouped product results while SKU searches can still match variant records. Set it to false if you want one hit per matching variant.

{
  "Ekom": {
    "Algolia": {
      "Search": {
        "GroupVariantsByProduct": false
      }
    }
  }
}

Additional product properties and metafields

Indexing:ProductProperties adds extra product properties and metafields to product records. Each entry supports one optional modifier: |array, |int, |decimal, |unix, or |unixms.

{
  "Ekom": {
    "Algolia": {
      "Indexing": {
        "ProductProperties": [
          "channels|array",
          "stockCount|int",
          "weight|decimal",
          "publishedAt|unix"
        ]
      }
    }
  }
}

Metafields can be indexed explicitly with metafield:<alias>:

{
  "Ekom": {
    "Algolia": {
      "Indexing": {
        "ProductProperties": [
          "metafield:material",
          "metafield:color|array",
          "metafield:releaseDate|unix"
        ]
      }
    }
  }
}

Modifier behavior:

• |array parses JSON arrays such as ["Web","Store"] into Algolia string arrays.
• |decimal accepts comma or dot decimal separators, such as 0,1 and 0.0.
• Multi-value metafields are skipped unless |array is configured.
• Invalid |array, |int, and |decimal values are skipped instead of being indexed as strings.

Manual reindexing

Use the backoffice endpoints to rebuild Algolia indexes manually. Both endpoints support GET and POST.

Rebuild all configured store indexes:

POST /umbraco/backoffice/api/Ekom/AlgoliaBackoffice/RebuildIndexes

Rebuild one store:

POST /umbraco/backoffice/api/Ekom/AlgoliaBackoffice/RebuildStoreIndexes?storeAlias=Store