Ad click attribution
Ad click attribution
When a visitor arrives from an ad, the landing URL carries a click id from the ad platform. WarpKit keeps it until sign-up and then stores it on the account. A conversion reported to the ad platform later, such as a trial started or the first paid invoice, needs that id: without it the platform accepts the upload and ties it to no click.
Nothing here talks to an ad platform. It stores the id, and it gives an admin a file of conversions to upload to Google Ads by hand (see Reporting conversions to Google Ads).
What is captured
| Parameter | From |
|---|---|
gclid | Google Ads |
gbraid, wbraid | Google Ads, for clicks on iOS |
msclkid | Microsoft Advertising |
utm_source, utm_medium, utm_campaign | Kept beside a click id, for reading the row |
Also the path the visitor landed on and the time. A URL with utm_
parameters and no click id is not stored: there is no id to report against.
How it works
- On landing,
CookieConsentBannercallsnoteLandingClick(), which reads the click from the URL and holds it in memory. Nothing is stored yet. - Consent decides. The click follows the same gate as the analytics
trackers (see Cookie consent):
- Banner on: the cookie is written when the visitor accepts the
analyticscategory. On "Reject all" the held click is dropped. A visitor who takes consent back loses the cookie. - Banner off: the cookie is written on landing.
- Banner on: the cookie is written when the visitor accepts the
- The cookie is
click_ref: first-party,SameSite=Lax, 90 days, the window in which Google Ads counts a conversion. A newer ad click replaces an older one. - At sign-up,
databaseHooks.user.create.afterinsrc/server/auth.tsreads the cookie from the request that created the account and writes one row touser_ad_clicks. This covers every sign-up path: code, magic link and OAuth. - The row is written once and never changed. It is deleted with the
account and included in the account's data export as
ad_click.
Where the code is
| File | What it holds |
|---|---|
src/lib/attribution/click.ts | The rules, with no DOM and no database: reading a URL, encoding and validating the cookie, and when to store. |
src/lib/attribution/browser.ts | The cookie write, and the three calls the banner makes. |
src/components/cookie-consent/CookieConsentBanner.tsx | Calls them as the consent gate decides. |
src/server/attribution.server.ts | Reads the cookie at sign-up and writes the row. |
src/lib/db/schema.ts | userAdClicks, the user_ad_clicks table. |
src/lib/attribution/conversions.ts | The names of the conversion actions and the CSV format. |
src/server/ad-conversions.server.ts | Reads the conversions from the tables. |
src/routes/api/v1/ad-conversions.ts | The admin download. |
src/pages/admin/ad-conversions-card.tsx | The link to it on the admin Analytics page. |
Reporting conversions to Google Ads
An admin downloads a file and uploads it in Google Ads. No developer token and no API access are needed, only the account.
The file. Admin, Analytics, "Ad conversions", "Download the file"
(src/pages/admin/ad-conversions-card.tsx). That link is
GET /api/v1/ad-conversions while signed in as an admin. Anyone
else gets a 404. Add ?since=2026-11-20 to get only the events from that day
on. It is a CSV in the format Google Ads imports:
Parameters:TimeZone=+0000
Google Click ID,Conversion Name,Conversion Time,Conversion Value,Conversion Currency
abc-1,Trial started,2026-11-20 09:05:07+0000,,
abc-1,First payment,2026-12-04 09:05:08+0000,9.00,USD
What is in it. Three events, for accounts whose click has a gclid:
| Event | Name in the file | Read from |
|---|---|---|
| Sign-up | Sign-up | The user_ad_clicks row, written at sign-up. |
| Trial started | Trial started | The subscriptions row, when it has a trial end. |
| First payment | First payment | The oldest row above 0 in payments or purchases. A refunded purchase is left out. |
Nothing is stored for this. The file is read from those tables each time, so it cannot drift from them.
In the Google Ads account, once. Create one conversion action per event
under Goals, Conversions, "Create conversion action", "Conversions offline",
with exactly the names above. Google matches the name letter for letter. To
use other names, change AD_CONVERSION_NAMES in
src/lib/attribution/conversions.ts. Mark as primary only the event the
campaigns should bid on. Wait 4 to 6 hours after creating an action before
the first upload.
Each upload. Goals, Conversions, Uploads, choose the file, then Preview
before Apply. Google takes 24 to 48 hours to count a row, and may not yet know
a click less than a day old. It refuses a row it already has, so a since
that overlaps the last upload only adds error lines to its report.
Limits.
- Clicks with only
gbraid,wbraidormsclkidare stored and not in the file. The file format has no column for them. - The file has no consent columns (
Ad User Data,Ad Personalization). Where the banner is on, a click is stored only after the visitor accepted the analytics category. Whether that is enough for visitors from the EEA is a question for the site owner to settle before uploading. - Google calls the file upload a legacy feature and recommends its Data
Manager or the API. The upload still works. Checked on 2026-11-20
(
support.google.com/google-ads/answer/7014069).
To read one click in code:
import { eq } from 'drizzle-orm';
import { db } from '@/lib/db';
import { userAdClicks } from '@/lib/db/schema';
const [click] = await db
.select()
.from(userAdClicks)
.where(eq(userAdClicks.userId, userId));
// click?.gclid, click?.clickedAt
What the visitor can send
The click id comes from a URL anyone can write and sits in a cookie the visitor
can edit. Both the browser and the server accept only a value shaped like a
real id (letters, digits, _ and -, at most 512 characters), drop unknown
fields, and refuse a click dated in the future or older than 90 days. A visitor
can still store a click id that is not theirs. The ad platform rejects an id
it did not issue.
Limits
- A visitor who lands, does not answer the banner and reloads the page loses the click: it was only in memory.
- An account created with no request of its own, such as one an admin creates, has no click.
- Sign-up in another browser or on another device than the click has no cookie to read.
Tests
src/lib/attribution/click.test.ts: the rules.src/server/attribution.server.test.ts: the row.src/server/attribution-signup.test.ts: a real sign-up by code through better-auth, so an upgrade that stops handing the hook the request fails a test.src/lib/attribution/conversions.test.ts: the file format.src/server/ad-conversions.server.test.ts: which events are reported.src/routes/api/v1/ad-conversions.test.ts: a visitor gets a 404.e2e/tests/admin/ad-conversions.spec.ts: an admin gets the file.e2e/tests/public/ad-click.spec.ts: the cookie in a browser, with the banner off. The consent library hides its banner from automated browsers, so the banner-on path is covered by the unit tests.