Algolia Insights

Datafly Signal delivers your search and conversion events to the Algolia Insights API server-side. These events power Algolia’s Click & Conversion Analytics, A/B test significance, Dynamic Re-Ranking, NeuralSearch, and the models behind Algolia Recommend.

Because Signal sends events from your own server using a stable first-party userToken, click and conversion signals keep flowing even when third-party cookies and client-side analytics calls are blocked.

Prerequisites

• An Algolia account with at least one search index.
• An Application ID and an API key with the search ACL. Find both in the Algolia dashboard under Settings > API Keys. Do not use your admin key.
• Click Analytics enabled on your search queries (clickAnalytics: true) so the search response returns a queryID. The queryID is what links a later click or purchase back to the search that produced it.
• Your front-end search must send the same userToken that Signal sends. Signal uses the visitor’s first-party _dfid identifier as anonymous_id; configure your Algolia front-end (InstantSearch / autocomplete) to use that same token so events are attributed to the right user.

Configuration

Configure in Signal

1. In your Signal management console, go to Integrations and add Algolia Insights.
2. Enter your Application ID, API Key, Index Name, and Region.
3. Attach the integration to the pipeline that carries your search and e-commerce events.
4. Choose the Search & Discovery preset. Map your store’s events to the Signal events it expects (Products Searched, Product List Viewed, Product Clicked, Product Viewed, Product Added, Order Completed).
5. Save and enable the pipeline.

API Endpoint

POST https://insights.{region}.algolia.io/1/events

Authentication is via two headers:

x-algolia-application-id: YOUR_APP_ID
x-algolia-api-key: YOUR_SEARCH_API_KEY
Content-Type: application/json

The request body wraps an array of up to 1,000 events (max 2 MB):

{ "events": [ { "eventType": "...", "eventName": "...", "index": "...", "userToken": "...", ... } ] }

A successful request returns a 2xx status.

Identity Signals

Algolia Insights is token-based, not PII-based — it does not accept email or phone. Identity is carried by two fields:

No hashing is applied — Algolia stores the tokens as opaque identifiers.

Event Mapping

For click and conversion after-search attribution, include the queryID returned by your search (as properties.query_id). For click events, positions must be the same length as objectIDs.

Example: a product click after search

Datafly.js call on your site:

datafly.track("Product Clicked", {
  query_id: "43b15df305339e827f0ac0bdc5ebcaa7",
  object_ids: ["9780201896831"],
  positions: [1]
});

Resulting Algolia Insights payload:

{
  "events": [
    {
      "eventType": "click",
      "eventName": "Product Clicked",
      "index": "products",
      "userToken": "df_8a1f3c2e9b",
      "authenticatedUserToken": "user_4823",
      "timestamp": 1717689600000,
      "queryID": "43b15df305339e827f0ac0bdc5ebcaa7",
      "objectIDs": ["9780201896831"],
      "positions": [1]
    }
  ]
}

Example: a purchase

datafly.track("Order Completed", {
  object_ids: ["9780201896831", "9780131103627"],
  currency: "USD",
  revenue: 64.5,
  products: [
    { "price": 29.99, "quantity": 1, "queryID": "43b15df305339e827f0ac0bdc5ebcaa7" },
    { "price": 34.51, "quantity": 1 }
  ]
});

Resulting payload (eventType: "conversion", eventSubtype: "purchase") carries objectIDs, objectData, currency, and value.

Testing

1. Trigger a search, a product click, and a purchase on your site.
2. In the Algolia dashboard, open Data Sources > Events (the Events Debugger). Valid events appear within a few seconds with their eventType, userToken, and index.
3. Confirm that click and conversion events show a queryID and are linked to a search — if they are not, your front-end is not sending clickAnalytics: true or the userToken does not match.
4. Check Search Analytics > Click & Conversion after a few hours to confirm click-through and conversion rates are populating.

Troubleshooting