Analytics Guide

Track and analyze search performance with Cludo analytics.

Cludo provides comprehensive analytics to help you understand how users search, what they find, and where to improve.

Tracking events

Analytics data is populated by tracking events. The recommended client-side setup is the Cludo API analytics script. If you use the React hooks from @cludosearch/cludo-search-components, analytics events are handled automatically by the components package. If you implement search directly via the API, send tracking events yourself.

Client-side event tracking

Track search events from your frontend. These endpoints accept any auth method, including anonymous requests with no auth header.

const BASE_URL = "https://api.cludo.com";
// Use https://api-us1.cludo.com for US region

async function trackSearch(customerId, engineId, queryId, query, resultCount) {
  await fetch(
    `${BASE_URL}/api/v3/${customerId}/${engineId}/search/pushstat/querylog`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        sw: query,
        qid: queryId,
        rc: String(resultCount),
        dt: "desktop"
      })
    }
  );
}

async function trackClick(customerId, engineId, queryId, clickUrl, clickIndex, title) {
  await fetch(
    `${BASE_URL}/api/v3/${customerId}/${engineId}/search/pushstat/clicklog`,
    {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        ls: "searchresult",
        sw: "search query",
        qid: queryId,
        clurl: clickUrl,
        cli: String(clickIndex),
        title: title
      })
    }
  );
}

The tracking body uses flat key-value pairs (for example {"sw": "query", "qid": "..."}). Do not wrap them in a values object. See API Reference → Tracking for the full list of parameters.

Server-side tracking and IP forwarding

If your integration sends tracking events from a backend rather than directly from the browser, the API receives your server’s IP instead of the real user IP. This affects analytics deduplication and geographic data.

To pass the real client IP, include it as an ip field in the request body:

body: JSON.stringify({
  sw: query,
  qid: queryId,
  rc: String(resultCount),
  dt: "desktop",
  ip: "203.0.113.42"   // real client IP captured server-side
})

The X-Real-IP, X-Forwarded-For, and Forwarded headers are not read by the tracking endpoints. The only supported way to pass a client IP from a server-side integration is the ip body field.

Viewing analytics

Analytics data is available in the Cludo Dashboard. The dashboard provides:

• Search term performance: top queries, zero-result queries, content gaps
• Search volume over time: total and trending search volume
• Click-through rate: are users finding what they need?
• AI analytics: volume & feedback scores