Coveo

Coveo is an AI-powered relevance platform for search, recommendations, and personalisation. Its Machine Learning models (Content Recommendations, Product Recommendations, and Automatic Relevance Tuning) are trained on usage analytics (UA) events — what visitors search for, view, click, and buy.

Datafly Signal delivers those events to Coveo server-to-server using the Coveo Usage Analytics (UA) Write API, so the signals that feed Coveo’s models survive ad blockers and browser tracking-prevention. Page and product views are sent as Coveo view events (which drive Content Recommendations) and behavioural interactions are sent as custom events.

Prerequisites

• A Coveo organization with usage analytics enabled.
• Your Organization ID — it forms the analytics host https://{organizationId}.analytics.org.coveo.com. You can find it in the Coveo Administration Console (the organization switcher, top-right) or in any platform URL.
• A Coveo API key with Push access to the Analytics Data domain. Create one in the Administration Console under Organization > API Keys, and enable the Push checkbox for the Analytics Data privilege.
• The search hub value your search interface uses (this becomes originLevel1 on every event and must match the searchHub in your Coveo Search API queries).

Configuration

Configure in Signal

1. In the Signal management UI, go to Integrations and add Coveo.
2. Enter your Organization ID, API Key, and Search Hub.
3. Select the Default preset. It maps the standard Datafly.js events to Coveo view and custom events.
4. Attach the integration to a pipeline and enable it.

API Endpoint

Events are sent to the org-specific UA Write host:

POST https://{organizationId}.analytics.org.coveo.com/rest/ua/v15/analytics/view    (view events)
POST https://{organizationId}.analytics.org.coveo.com/rest/ua/v15/analytics/custom  (custom events)

Authentication is a bearer token:

Authorization: Bearer <api_key>
Content-Type: application/json

The API key must have Push access to the Analytics Data domain. A 403 response means the key is missing that privilege; a 404 usually means the Organization ID in the host is wrong.

Identity Signals

Coveo stitches a visit using clientId, a stable per-visitor identifier. Signal maps its first-party canonical identifier (anonymous_id, persisted in the _dfid cookie) into clientId, so the same visitor is recognised across page loads server-side. The anonymous flag is derived from marketing consent (a consenting/known visitor is sent as anonymous: false), and the logged-in user_id is sent as username when available.

No personally identifiable data is hashed or required by the UA Write API — Coveo’s models work on behavioural signals keyed by clientId.

Event Mapping

The Default preset maps Datafly.js events to Coveo UA events:

Every event also carries language (ISO 639-1, derived from the locale), userAgent, clientId, and the configured originLevel1. All events not in the table are dropped.

Example: a product view

Datafly.js call on a product detail page:

datafly.track("Product Viewed", {
  product_id: "SP-1024",
  product_name: "Trail Runner GTX",
  brand: "Acme",
  category: "Footwear",
  price: 129.99
});

Resulting Coveo /view payload:

{
  "clientId": "489aa3e3-aed2-4563-8e81-62bb73178a56",
  "language": "en",
  "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...",
  "originLevel1": "default",
  "anonymous": false,
  "location": "https://shop.example.com/p/trail-runner-gtx",
  "title": "Trail Runner GTX",
  "contentIdKey": "permanentid",
  "contentIdValue": "SP-1024",
  "contentType": "Product",
  "customData": {
    "productName": "Trail Runner GTX",
    "brand": "Acme",
    "category": "Footwear",
    "price": 129.99
  }
}

The contentIdKey / contentIdValue pair is what Coveo’s Content Recommendations model uses to associate the view with an item in your index. Set contentIdKey to the index field that uniquely identifies the item (commonly permanentid for commerce catalogues).

Testing

1. Trigger events on a page that has Datafly.js installed (a product view, a search, a purchase).
2. In the Coveo Administration Console, open Analytics > Visit Browser and find the current visit by clientId. View and custom events should appear within a minute.
3. Use the UA metadata validation tools in the console to confirm originLevel1, language, and contentIdValue are populated as expected.

Troubleshooting

• 403 Forbidden — the API key lacks Push access to the Analytics Data domain. Edit the key in Organization > API Keys and enable the Push privilege for Analytics Data.
• 404 Not Found — the Organization ID in the host is wrong. Confirm it in the console; the host must be https://{organizationId}.analytics.org.coveo.com.
• 400 with a missing-field error — originLevel1 is required. Set the Search Hub field in the integration config.
• Events don’t appear in recommendations — confirm originLevel1 matches the searchHub used in your Search API queries, and that view events carry a valid contentIdKey/contentIdValue that resolves to an item in your index. Models also need a training window before recommendations reflect new signals.
• Wrong language attribution — Coveo requires an ISO 639-1 code (en, not en-GB). Signal sends the language part of the locale; if your locale values are non-standard, add a transform on the language field.