---
title: Click IDs
description: How to attach ad-platform Click IDs to events and short links, and the full list of the 29 platforms Retidal recognizes.
---

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](/docs/sending-data/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`.

<Warning>
  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`.
</Warning>

### 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;
}
```

<Note>
  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](/docs/attribution/short-links).
</Note>

## 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.

<Table searchable>
| 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` |
</Table>

<Warning title="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.
</Warning>

## What this unlocks

A Click ID attached to an event is what [Ad platforms](/docs/attribution/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

<Warning title="Use a sandbox project, or an event name with no mapping">
  An event carrying a Click ID whose `eventName` has a live
  [Event mapping](/docs/sending-data/event-mappings) triggers a real conversion
  callback to that ad platform (see [Ad platforms](/docs/attribution/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.
</Warning>

```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](/docs/troubleshooting/attribution-looks-wrong).

## Next steps

<CardGroup cols={2}>
  <Card title="Ad platforms" href="/docs/attribution/ad-platforms">
    How Click IDs turn into a conversion callback on the platform's side.
  </Card>
  <Card title="Short links" href="/docs/attribution/short-links">
    Let short-link redirects capture Click IDs for you automatically.
  </Card>
</CardGroup>