Click IDs

When someone clicks an ad, the ad platform appends a Click ID parameter to the landing URL — the token Retidal needs to report conversions back to that platform. This page covers how to get Click IDs into Retidal and lists every platform parameter it recognizes.

Prerequisites

• Events already flowing through Sending events — Click IDs are attached to events, not sent on their own.

How to send a Click ID

There are three ways to attach Click IDs to an event; use the first wherever you can.

1. The clickIds object (recommended)

A single object covering all 29 platforms:

json

{
  "eventName": "user_paid",
  "visitorId": "vid_abc123",
  "clickIds": { "bd_vid": "abc123", "gclid": "xyz789" }
}

This is the only path that reaches every platform, including the ones added most recently (see the ⚠️ note on legacy fields below).

2. A top-level click_id

A single generic click_id field, for cases where you only need to carry one identifier through.

3. Legacy top-level typed fields

Fields like bdVid, gclid, fbclid sent directly at the top level of the event. These only cover the earlier ~15 platforms — anything added since must go through clickIds.

New platforms are only wired up through the clickIds object. If you’re integrating a platform not covered by the legacy typed fields, don’t look for a matching top-level field — use clickIds.

From a page URL

If you’re extracting Click IDs from window.location yourself before reporting an event, matching is case-sensitive — globalId, clickId, and ScCid must be read with their exact casing, not lowercased.

javascript

function extractClickIds(url = window.location.href) {
  const params = new URL(url).searchParams;
  const clickIdParams = [
    "bd_vid", "clickid", "click_id", "gdt_vid", "callback",
    "xhs_click_id", "buvid", "weibo_cid",
    "gclid", "fbclid", "ttclid", "msclkid", "twclid",
    "li_fat_id", "ScCid", "epik",
  ];
  const clickIds = {};
  for (const param of clickIdParams) {
    const value = params.get(param);
    if (value) clickIds[param === "click_id" ? "clickid" : param] = value;
  }
  return clickIds;
}

Short links (GET /s/{code}) already extract all 29 platforms’ Click IDs from the inbound query string automatically — you only need code like the above for direct-landing pages that never go through a Retidal short link. See Short links.

The 29 supported platforms

This is the authoritative parameter list — the same list both the short-link redirect and event ingestion use to extract Click IDs.

Category	Platform	Click ID parameter(s)
Domestic (CN)	Baidu oCPC	bd_vid
Domestic (CN)	Douyin / Oceanengine	clickid
Domestic (CN)	Tencent Ads	gdt_vid
Domestic (CN)	Kuaishou	callback
Domestic (CN)	Kuaishou KWAI	clickid
Domestic (CN)	Xiaohongshu	xhs_click_id
Domestic (CN)	Bilibili	buvid
Domestic (CN)	Weibo	weibo_cid
International	Google Ads	gclid / gbraid / wbraid
International	Google Measurement (GA4 MP)	client_id — SDK clickIds only, not extracted from URL
International	Meta / Facebook	fbclid
International	TikTok	ttclid
International	Microsoft / Bing Ads	msclkid
International	Twitter / X Ads	twclid
International	LinkedIn Ads	li_fat_id
International	Snapchat Ads	ScCid
International	Pinterest Ads	epik
International	Bigo	bbg
Programmatic	TrafficStars / Xiaobu	click_id
Programmatic	TrafficJunky	aclid
Programmatic	PropellerAds	subid
Programmatic	DeepClick	abclid
Programmatic	Mgsky	pixel_click_id
Attribution / traffic	Adjust	adid / gps_adid
Attribution / traffic	OkSpin	tkid
Attribution / traffic	Snaptube	globalId
Attribution / traffic	AppLuck	clickId
Attribution / traffic	Macan	clk_id

GA4's client_id is intentionally excluded from URL extraction

Google Measurement (GA4 Measurement Protocol)’s client_id is deliberately not pulled from the URL query string — it’s too generic and collides with OAuth’s own client_id convention. If you need to report GA4 conversions, send client_id through the clickIds object explicitly.

What this unlocks

A Click ID attached to an event is what Ad platforms uses to send a conversion callback back to the platform the click came from — no Click ID, no callback, regardless of whether the event itself was received correctly.

Verify it worked

Use a sandbox project, or an event name with no mapping

An event carrying a Click ID whose eventName has a live Event mapping triggers a real conversion callback to that ad platform (see Ad platforms) — do this against a sandbox/test project, or first confirm the event name below has no event mapping, automation, or derived rule subscribed to it in whatever project you test against.

bash

curl -s -X POST https://api.retidal.com/api/v1/t \
  -H "X-API-Key: $RETIDAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"eventName":"click_id_verify_test","visitorId":"vid_abc123","clickIds":{"gclid":"xyz789"},"_debug":1}'
# expect: 202 { "accepted": 1, ... } — then check the event's clickIds on
# Console → Projects → Debug (with debug mode enabled) to confirm the platform's
# Click ID parameter actually landed on the stored event

If it doesn’t work

If the Click ID never reaches the platform postback (conversion credit is missing or attributed to the wrong click), work through Attribution looks wrong.

Next steps

Ad platforms

How Click IDs turn into a conversion callback on the platform’s side.

Short links

Let short-link redirects capture Click IDs for you automatically.