Skip to content

About

Know which ad produced which phone call, and keep the caller's number. Cloudflare Worker + offline conversions back into Google Ads.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

gads-call-tracking

Know which ad produced which phone call — and keep the caller's number.

A call tracking stack you own: a Cloudflare Worker, a 90-line snippet, and one Python script that sends qualified calls back to Google Ads as offline conversions with a value attached.

python3 upload_call_conversions.py --customer-id 123-456-7890 \
    --conversion-action 987654321 --site https://example.com --value 120

Dry run by default. Nothing is uploaded until you add --live.


Why this exists

Google's own call reporting tells you a call happened. It does not tell you who called, and it stops at the boundary of the ad: a visitor who lands on your site and dials the number printed there is invisible to it.

Paid tools solve this for $45–$300 a month. They all keep the two things worth having — the caller's number and the call duration — inside their dashboard, and none of them close the loop back into Smart Bidding with your real revenue.

This does both, on infrastructure you already pay for.


How it works

  1. A visitor arrives with a gclid. The snippet asks the worker for a number.
  2. The worker leases one number from your pool to that click for 30 minutes.
  3. The visitor calls. Your provider forwards the tracking number to your real line and posts the finished call back — caller id, duration, start time.
  4. The worker matches the call to the click that held the number.
  5. The daily upload sends qualified calls to Google Ads with a value, so bidding optimises toward the calls that are actually worth something.
ad click ──▶ /api/number ──▶ leased number shown on the page
                                      │
                       visitor dials ─┘──▶ provider ──▶ /api/call-events
                                                              │
                              /api/calls?pending=1 ◀──────────┘
                                      │
                    upload_call_conversions.py ──▶ Google Ads

What it costs

One tracking number per simultaneous ad visitor, not per visitor per day. A number returns to the pool as soon as its call ends or after 30 minutes.

Ad clicks/day Pool that covers it Twilio, roughly
under 50 2–3 numbers $2–4/month
50–200 4–6 numbers $5–8/month
200–1000 8–15 numbers $10–20/month

Cloudflare Workers and KV cover this on the free tier at small volume.


Install

git clone https://github.com/solernicolas041/gads-call-tracking
cd gads-call-tracking

wrangler kv namespace create CALLS          # note the id it prints
cp wrangler.toml.example wrangler.toml      # paste the id in
wrangler pages secret put CALL_WEBHOOK_TOKEN --project-name your-site

Copy functions/api/ into your site's repo and snippet/call-tracking.js into your assets, then load it on every page that shows a phone number:

<script src="/call-tracking.js" data-number="(415) 555-0100,415-555-0100"></script>

data-number lists your number exactly as it is printed on the page — every spelling you use. The snippet rewrites the visible text and the tel: links together; a link that does not match the number under the reader's eyes is the surest way to lose the call it was meant to measure.

Configure the pool without a deploy

Numbers live in KV, not in the code, so renting or releasing one never requires shipping the site:

# what the site shows when tracking is off, unavailable, or exhausted
wrangler kv key put --binding CALLS "config:fallback" "+14155559999|(415) 555-9999"

# the rented lines, as "e164|what to print", comma separated
wrangler kv key put --binding CALLS "config:pool" \
  "+14155550100|(415) 555-0100,+14155550101|(415) 555-0101"

No config:pool = empty pool = the site swaps nothing and behaves exactly as it did before you installed this. That is the safe default, and the intended way to deploy the code first and switch tracking on later.

Then wire your phone provider: examples/twilio-webhook.md.


Prove it before you rent a line

python3 simulate_call.py --site http://localhost:8788 --token dev-token
1. an ad visitor lands on /quote
   the page now shows (415) 555-0100  (+14155550100)
2. that visitor calls, 95s
   recorded — attributed: True, billable: True
3. what the daily upload would pick up
   14155551234 · 95s · click demo-a1b2c3d4e5f6 · /quote
DONE — 1 call(s) waiting to be sent to Google Ads.

The mistakes this refuses to make

A call must never depend on this code. Empty pool, unreachable KV, malformed response, network down, no click id: every path leaves the page showing your real number. The failure mode is "no attribution", never "no phone number".

A short call is not a conversion. Under 60 seconds — Google's own threshold — a call is stored for your callback list and never uploaded. Uploading them would teach Smart Bidding to buy wrong numbers.

The wrong conversion action type fails silently. A call uploaded onto an UPLOAD_CLICKS action, or onto a paused action, returns HTTP 200 and records nothing at all. The script reads the action back from the API and refuses:

FAILED — 'Contact form' is UPLOAD_CLICKS, not UPLOAD_CALLS.
Uploading calls to it is accepted by the API and records nothing.

An hour of drift is a silent non-match. Google matches on caller id and start time, so the start time is converted into the account's own time zone, read from the API — never assumed, never hardcoded.

A rejected call is not a lost call. Only the rows Google actually accepted are marked as sent. The rest stay pending and go out tomorrow.


Tests

node --test tests/*.mjs      # 22 tests, fake KV, no Cloudflare account needed
python3 tests/test_upload.py # 22 tests, no credentials, no network

The worker tests fake the store's failure modes on purpose: endpoints that only work when KV is healthy are not worth deploying in front of a phone number.


What this does not do

  • Call recording and transcription. Out of scope, and a much heavier legal ask in most jurisdictions.
  • Attribution for organic and direct visitors. They see your real number by design. You are renting lines to measure paid clicks, not everyone.
  • Consent and retention. You are storing customers' phone numbers. Under GDPR that is personal data: say so in your privacy notice, and delete it on a schedule. KV expirationTtl on the call: keys is a one-line way to do it.
  • Anything about Bing, Meta or organic channels. The click ids it understands are gclid, wbraid and gbraid.

Related

MIT. Built by SolerAds.

About

Know which ad produced which phone call, and keep the caller's number. Cloudflare Worker + offline conversions back into Google Ads.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages