Sources

A source is one place your events come from: a website, a web app or a server. A project can have several, and people are stitched together across them. Sources is where data comes in.

Updated

What a source is

Your marketing site, your app and your backend are three sources in one project. Keep them in one project, so a funnel can start on the site and end at a server event such as Invoice paid. Each source has its own key, health and settings.

Add a source

  1. Go to Sources and click Add source, or press ⌘K and choose Add source.
  2. Pick a type:
    • Website: a script tag for your <head>, with autocapture on.
    • Web app: the same script, plus your own events and identify.
    • Server: a secret key and the Node SDK or HTTP API.
  3. Give it a name and, for a website or web app, its domain.
  4. Click Create source (or Create server source).

If the new domain differs from one you already track, you are offered Carry identity between the two, which is on by default. See Identity. Mobile app sources, with native SDKs for iOS and Android, are coming soon.

Install a website or web app

A browser source’s page has an Install card with the snippet and a Copy button. Paste it into the <head> of every page. The source key in it is public: the script sends it with every event, so it is safe in your HTML. Framework notes and checks are in Install the tracker.

Until the first event arrives, the page says Waiting for the first event, with Copy snippet and Check again. Events from a domain you haven’t listed are rejected.

Install a server source

A server source’s page is its install page:

  1. Create a secret key. It opens by itself for a new server source.
  2. Store it as CLICKCLACKS_SERVER_KEY.
  3. Run npm install @clickclacks/node and send an event with the quick start. There is a Cloudflare Workers example too.
  4. Not on Node? Use the curl, Python or Go examples under Not on Node?.

The status light switches from Waiting for the first event to Receiving · last event 4s ago. The Server API health card shows the last event received, events, rejections and rate limits in the last 24 hours, plus which SDKs are calling. If a browser ever tries to use the key, it warns you and offers to roll it. The full reference is Server-side tracking.

Server keys

Server keys live on each server source’s page, under Secret keys. A key can only send events to that source, never read.

  • Create key: name it (for example Production) and copy it from Copy your server key. It is shown once and stored as a hash.
  • A source can have two working keys at a time.
  • Roll a key to replace it. Choose Stop the old key now, Keep the old key for 24 hours or Keep the old key for 7 days, so you can deploy the new one without dropping events.
  • Revoke takes effect on the next request and can’t be undone.

Health

The Sources list shows each source’s type, domain, events and people in the last 30 days, and its health:

HealthMeans
ReceivingAn event arrived in the last 30 minutes.
QuietThe last event was under 24 hours ago.
Stopped sendingNothing for 24 hours or more.
Waiting for eventsThe source has never sent anything.

On a source’s page, a banner warns when nothing has arrived for much longer than usual for that source, with a checklist of things to look at. The page also shows events and people in the last 30 days, distinct events, and rejected events.

Source settings

  • Autocapture clicks (browser sources): record clicks without any code.
  • Filter known bots: drop known bots before they are stored or counted.
  • Record IP address: off means country only.
  • Carry identity (browser sources): keep one person as one person across your listed domains.

Remove this source stops collection straight away. Existing events are kept for 30 days before they are removed for good.

Sources vs API access

Keys are split by direction:

  • Data in lives in Sources: each browser source’s public source key, and each server source’s secret keys.
  • Data out lives in Settings › API access: read-only MCP & analytics keys that let Claude, Codex or your scripts read the project’s analytics. See MCP server.

Tips and gotchas

  • One product, one project. Put your site and app in the same project as separate sources, not in two projects.
  • Want the script on your own domain? See Custom domain.
  • Every event counts toward your plan except identify, alias and merge calls. Events your source filters out, such as known bots, are never counted. See Settings › Usage & plan.

Recipes

Track subscription renewals from the backend.

  1. Click Add source, choose Server, name it Billing backend and click Create server source.
  2. Create a key and store it as CLICKCLACKS_SERVER_KEY.
  3. Send Subscription renewed with the customer’s user ID as distinctId, the same ID your app sends to identify.
Renewals now join the same people as their browser activity, so a funnel can go from pricing page to renewal.

Our app stopped showing data. Where do I start?

  1. Open Sources and find the app’s health. Stopped sending means nothing for 24 hours.
  2. Open the source and check Rejected events and the warning card.
  3. Click Inspect live events and load a page of your app.

Rotate a server key without dropping events.

  1. On the server source’s page, click Roll on the current key.
  2. Choose Keep the old key for 24 hours and copy the new key.
  3. Deploy the new key. The old one stops by itself after 24 hours.
If a key has leaked, choose Stop the old key now instead, and accept a short gap while you deploy.

Related