> ## Documentation Index
> Fetch the complete documentation index at: https://algolia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Install with Composer">
    ```sh icon="square-terminal" theme={"system"}
    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
    ```
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

<Note>
  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.
</Note>

## 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.

<Warning>
  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](#backend-rendering-modes)
  or make sure Magento's full-page cache is active so that server-rendered responses are served from cache.
</Warning>

## 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.

## 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**.

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

## 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.