Click Feedback

How it works#

1. Every search response carries a queryId, such as q_7d2k9x1m4q8z0a3b. It names that search.
2. When someone clicks a result, send a search_result_click event with the queryId and the result's document id. Send a conversion when they buy or sign up.
3. Turn on "Use click feedback in ranking" in the dashboard (Indexes, the pointer button on the index) or with the API. Pick a strength. It is off by default.

Send events#

{
  "events": [
    {
      "type": "search_result_click",
      "index": "products",
      "docId": "123",
      "queryId": "q_7d2k9x1m4q8z0a3b",
      "position": 3,
      "sessionId": "s_8f2k1m"
    },
    {
      "type": "conversion",
      "index": "products",
      "docId": "123",
      "queryId": "q_7d2k9x1m4q8z0a3b",
      "sessionId": "s_8f2k1m",
      "value": 8900
    }
  ]
}

{
  "accepted": 2,
  "rejected": []
}

With the React SDK, useClickTracking() fills in the index, the queryId, the position and a session id. It is in @headband/react 0.2.1, which is not on npm yet. Until then, post the events to /v1/relevance/events yourself.

import { useClickTracking, useHits } from "@headband/react";

function Results() {
  const { hits } = useHits();
  const { trackClick } = useClickTracking();
  return hits.map((hit, i) => (
    <a key={String(hit.id)} href={String(hit.url)} onClick={() => trackClick(hit, i)}>
      {String(hit.title)}
    </a>
  ));
}

// On the order page. It names the search the product was clicked from.
const { trackConversion } = useClickTracking();
trackConversion(productId, { value: 8900 });

Without React: client.trackClick(...), client.trackConversion(...) and client.sendEvents([...]) on the headband() client. Events go out with keepalive, so a click that opens a new page still arrives.

Turn it on#

{
  "enabled": true,
  "strength": 0.5
}

{
  "index": "products",
  "engine": "typesense",
  "enabled": true,
  "strength": 0.5,
  "window": 50,
  "support": { "ranking": true, "note": "..." },
  "engines": { "typesense": { "enabled": true, "strength": 0.5, "updatedAt": "..." } }
}

How ranking changes#

• Clicks count per query. A click on a result for "trail shoes" lifts it for "trail shoes", not for every query. Case, width and extra spaces do not matter: "Trail Shoes" is the same query.
• Headband asks the engine for the top 50 results, keeps the engine's order as the base, and adds each result's click score for the query. A result outside the top 50 cannot be pulled in, and pages past result 50 are exactly the engine's.
• A conversion counts 5 clicks. A click lower down counts more than one at the top (a click at position 9 counts 3), because people click the first result most whatever it is. A click on a result the named search did not show counts a quarter.
• Scores halve every 14 days, so old clicks fade.
• Some searches are left as the engine ranks them: an empty query, an explicit sort, page or hitsPerPage paging, and a page that needs more than 250 results. The X-Headband-Click-Feedback response header says what happened: applied, off, empty_query, sorted, paged, deep_page, too_many or invalid.
• /v1/search and /v1/multi-search use it. Hybrid search, AI search and the engines' own APIs do not.

Engines#

Every engine gets the same re-rank, so a strength means the same thing whichever engine an index runs on. Nothing is written into your documents and no setting or schema changes, so turning it on never reindexes or rebuilds anything.

One visitor cannot game it#

• The same visitor clicking the same result again within 30 minutes counts once.
• One session, and one network address, can add at most 5 to a result per day. At the default strength that moves it about two places at most.
• A session counts at most 50 events an hour.
• A search key sends at most 120 event requests a minute from one address. Crawlers and headless browsers are refused as bot.
• Admin keys are trusted, for servers that send events for many visitors: no session or address caps, but repeats still count once.

What is stored#

Before a query is stored, emails, phone numbers, card numbers, US social security numbers, IP addresses, runs of 9 or more digits and Headband keys in it are replaced with tokens such as [email]. The query sent to the engine is not changed. DELETE /v1/indexes/{uid}/click-feedback (or "Delete click data" in the dashboard) deletes everything at once, and deleting an index deletes its click data with it.