Backend search adapter

Enable server-side rendering for search and category pages with the Algolia Search Adapter for Magento.

The Algolia Search Adapter registers Algolia as a native Magento 2 search engine and provides backend (server-side) rendering for category pages and search results.

When enabled, Magento’s standard product listing blocks query Algolia directly (no InstantSearch JavaScript required) making content visible to search-engine crawlers, LLM-based discovery tools, and any client that doesn’t run JavaScript.

The adapter is available starting with version 3.18 of the Algolia extension.

Install the search adapter

1. Install with Composer

   composer require algolia/algoliasearch-adapter-magento-2
   php bin/magento module:enable Algolia_SearchAdapter
   php bin/magento setup:upgrade
   php bin/magento setup:di:compile
   php bin/magento cache:flush
   
2. Configure Algolia credentials

   If you haven’t already, go to Stores > Configuration > Algolia Search > Credentials and Basic Setup and enter your Algolia Application ID and API keys. The adapter uses the same credentials as the main extension.

3. Set Algolia as the search engine

   1. Go to Stores > Configuration > Catalog > Catalog Search.
   2. Set Search Engine to Algolia Backend Search.
   3. Adjust connection and read timeouts if needed (defaults: 2 s / 5 s).
   4. Click Test Connection to verify connectivity.
   5. Save and flush cache.

You don’t need to uninstall Elasticsearch or OpenSearch. Changing the search engine setting is enough. Magento routes all search queries to whichever engine is selected.

Work with and without InstantSearch

The adapter can operate in two ways:

• Without InstantSearch (pure server-side rendering). Magento renders product listings and layered navigation entirely on the server. This is useful if you don’t need client-side search features or want a lightweight setup for SEO.

• With InstantSearch (hybrid mode). Server-rendered pages are delivered to bots and non-JS clients, while human visitors get the full InstantSearch experience. The adapter respects your existing InstantSearch facet and sorting configuration, so both rendering paths return consistent results.

In hybrid mode, each page load can trigger two sets of Algolia API requests: one from the server-side render and one from InstantSearch on the client. To avoid doubling your search operations, enable backend rendering for specific User Agents only or make sure Magento’s full-page cache is active so that server-rendered responses are served from cache.

Supported pages and limitations

The adapter handles two page types:

• Quick search results (catalogsearch/result)
• Category pages (product listings)

Landing Pages and Advanced Search aren’t supported at this time.

Events and analytics

Backend rendering serves static HTML to crawlers, LLM-based discovery tools, and other clients that don’t run JavaScript. Because there’s no client-side layer to capture user interactions, backend-rendered pages don’t send click and conversion events to Algolia, and the responses behind them don’t return a queryID.

What this means depends on how you run the adapter:

• Standalone backend rendering (without InstantSearch). No click or conversion events are captured, so search analytics that rely on events aren’t available for these pages.
• Hybrid mode (with InstantSearch). Interactive visitors still get the full InstantSearch experience, which captures click and conversion events as usual. The server-rendered variant served to crawlers doesn’t generate events, which is expected because no client-side interactions occur.

To capture click and conversion analytics, run the adapter in hybrid mode with InstantSearch enabled. See Click and conversion events to set up tracking.

Why backend rendering doesn’t capture a queryID

Backend-rendered pages don’t generate click and conversion events. This is expected because backend-rendered pages are served from a shared cache, so they can’t reliably associate events with an individual search. To avoid incorrect analytics, the adapter doesn’t enable click analytics for backend-rendered queries.

SEO-friendly filters

By default, Magento encodes filter selections as internal option IDs:

?color=49&size=167

With SEO-friendly filters enabled, the adapter converts these to human-readable labels:

?color=blue&size=large

To configure this setting, go to Stores > Configuration > Catalog > Catalog Search > Enable SEO Friendly Filters.

Keep this setting enabled when using both backend rendering and InstantSearch. It ensures both rendering modes produce identical, indexable URLs.

Query string parameter parity

When a crawler indexes a backend-rendered URL like ?product_list_order=price~asc&p=2&cat=5&price=10-50, a human visitor opening the same URL should get identical results from InstantSearch. The query string parameters setting ensures both modes use matching URL parameter names.

Parameter	Algolia default mode	Magento compatibility mode (default)
Sorting	sortBy	product_list_order
Pagination	page	p
Category	categories	cat
Price	price.{priceKey} with : separator	price with - separator

To configure, go to Stores > Configuration > Algolia Search > InstantSearch > Backend Search Compatibility > Query string parameters.

Backend rendering modes

Backend rendering controls whether Magento renders product listings on the server before delivering the page.

Mode	Behavior
No (default)	InstantSearch handles all rendering client-side.
Yes (for all users)	The server renders results for every request.
Yes, for specific User Agents	The server renders only when the request’s User-Agent matches the allow list.

To configure, go to Stores > Configuration > Algolia Search > InstantSearch > Backend Search Compatibility.

User-agent allow list

When the rendering mode is set to specific User Agents, you can configure which user agents receive server-rendered pages. Enter one user-agent string per line. Matching is partial and case-insensitive. For example, Googlebot matches Mozilla/5.0 (compatible; Googlebot/2.1; ...).

The defaults are Googlebot and Bingbot.

Cache context

When backend rendering targets specific user agents, the module adds an algolia_rendering_context value (with_backend or without_backend) to Magento’s X-Magento-Vary cookie. This tells Magento’s full-page cache to store separate cached pages for bot visitors and human visitors, so each group gets the correct rendering.

This context only applies when InstantSearch is configured to replace category pages.

Varnish and user-agent caching

When using the specific User Agents mode behind Varnish, be aware of an important caching interaction.

The module uses the X-Magento-Vary cookie to differentiate bot and human requests. This works with Magento’s built-in full-page cache. However, search-engine crawlers don’t carry cookies, so Varnish has no X-Magento-Vary value to distinguish bot requests from human requests on cache hits.

Without intervention, Varnish may serve the wrong cached variant. If this were to happen, a human could see the bot (backend-rendered) page, or a crawler could see the JavaScript-only page.

This can be addressed in one of three ways:

1. Custom VCL snippet (recommended). Add a VCL rule that inspects the User-Agent header and synthesizes or overrides the vary hash for known bot user agents. This ensures Varnish serves the correct variant without relying on cookies.

2. Use “Yes (for all users)” mode. When every visitor gets the same server-rendered page, there’s no variant mismatch to worry about.

3. Bypass Varnish for bot traffic. Route known bot user agents directly to the Magento backend, skipping Varnish entirely.