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

ParameterFrom
gclidGoogle Ads
gbraid, wbraidGoogle Ads, for clicks on iOS
msclkidMicrosoft Advertising
utm_source, utm_medium, utm_campaignKept 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

  1. On landing, CookieConsentBanner calls noteLandingClick(), which reads the click from the URL and holds it in memory. Nothing is stored yet.
  2. 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 analytics category. 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.
  3. 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.
  4. At sign-up, databaseHooks.user.create.after in src/server/auth.ts reads the cookie from the request that created the account and writes one row to user_ad_clicks. This covers every sign-up path: code, magic link and OAuth.
  5. 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

FileWhat it holds
src/lib/attribution/click.tsThe rules, with no DOM and no database: reading a URL, encoding and validating the cookie, and when to store.
src/lib/attribution/browser.tsThe cookie write, and the three calls the banner makes.
src/components/cookie-consent/CookieConsentBanner.tsxCalls them as the consent gate decides.
src/server/attribution.server.tsReads the cookie at sign-up and writes the row.
src/lib/db/schema.tsuserAdClicks, the user_ad_clicks table.
src/lib/attribution/conversions.tsThe names of the conversion actions and the CSV format.
src/server/ad-conversions.server.tsReads the conversions from the tables.
src/routes/api/v1/ad-conversions.tsThe admin download.
src/pages/admin/ad-conversions-card.tsxThe 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:

EventName in the fileRead from
Sign-upSign-upThe user_ad_clicks row, written at sign-up.
Trial startedTrial startedThe subscriptions row, when it has a trial end.
First paymentFirst paymentThe 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, wbraid or msclkid are 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.