Ad Click Attribution Pipeline

Ad Click Attribution Pipeline

You've joined Ads Measurement. adtrack ingests raw tracker events (impressions and clicks) from the web and mobile SDKs and produces the hourly delivery report that billing reconciles against. This sprint you own three tickets: a billing discrepancy in the hourly report, a new reach report, and last-click conversion attribution.

Codebase

How your code is run

run(operations: list) -> list creates a fresh service, executes each operation in order and returns one output per operation.

A raw event is an object: event_id (string or integer; 7 and "7" are the same id), type (case-insensitive, surrounding spaces ignored), campaign_id (string or integer, normalised to a string), user_id (string; see Part 1), ts (epoch seconds, may be fractional).

Unknown operations return "error: unknown operation: <name>".

Ingest rules (existing behaviour). A payload is rejected if it isn't an object, has a missing/blank event_id or campaign_id, an unsupported type, or a ts that is not a number (booleans and strings don't count) or is negative. A payload whose event_id was already ingested, in this batch or an earlier one, is a duplicate and is ignored. Events may arrive out of order.

Hourly report. Hours are epoch-aligned buckets [h, h + 3600). Each row is {"hour": h, "impressions": n, "clicks": n, "ctr": clicks / impressions rounded to 4 places (0.0 when impressions is 0)}. A row is returned for every hour h with from_ts <= h < to_ts that has at least one event for the campaign, in ascending order.

Worked example (H = 1767225600, i.e. 2026-01-01T00:00:00Z; write it as the literal number):

[["ingest", [
   {"event_id": "e1", "type": "impression", "campaign_id": "cmp-7", "user_id": "u1", "ts": 1767229200.4},
   {"event_id": "e2", "type": "click",      "campaign_id": "cmp-7", "user_id": "u1", "ts": 1767229260},
   {"event_id": "e2", "type": "click",      "campaign_id": "cmp-7", "user_id": "u1", "ts": 1767229260},
   {"event_id": "e3", "type": "purchase",   "campaign_id": "cmp-7", "user_id": "u1", "ts": 1767229300}]],
 ["hourly_report", "cmp-7", 1767225600, 1767312000]]

returns

[{"accepted": 2, "duplicates": 1, "rejected": 1},
 [{"hour": 1767229200, "impressions": 1, "clicks": 1, "ctr": 1.0}]]

Part 1 — Hourly report disagrees with the raw logs

Goal: make the hourly report match the raw logs exactly. Two reports from this week:

• *Billing:* "Every hour a few clicks are counted in the next hour's row. They're always events logged in the last moments of the hour, e.g. a click at 1767229199.6 (00:59:59.6) shows up under 01:00."
• *On-call:* "Since the web SDK started sending logged-out traffic, any ingest batch containing an event with "user_id": null blows up and none of the batch is processed."

Rules

1. Fractional timestamps are truncated to whole seconds (1767229199.999 is second 1767229199, in the hour starting 1767225600). This applies everywhere timestamps are used.
2. user_id that is null, missing, or blank/whitespace-only means *logged out*. Such events are valid: they are accepted and count in the hourly report like any other.
3. Nothing else about ingest or the hourly report changes.

Part 2 — Reach report (ADS-412)

Goal: implement reach in adtrack/reach.py: how many distinct people saw a campaign recently, and how often.

Rules

1. The window is end_ts - window_seconds < ts <= end_ts (start exclusive, end inclusive), using truncated timestamps.
2. Only impressions count, and only from identified users (non-null user_id). Clicks and logged-out impressions are ignored entirely. Only the requested campaign counts.
3. Return {"users": U, "identified_impressions": I, "frequency": F, "distribution": D}:

• U = number of distinct users with at least one counted impression;
• I = number of counted impressions (duplicates by event_id are already dropped at ingest);
• F = I / U rounded to 2 decimal places, 0.0 when U is 0;
• D = {"1": a, "2": b, "3+": c}: how many users saw the campaign exactly once, exactly twice, three or more times. All three keys are always present.

Example. Impressions for cmp-1 at H (u4), H+100 and H+200 (u1), H+300 (u2), H+400 (user_id null), a click at H+450 (u3), and an impression at H+3700 (u3). ["reach", "cmp-1", H+3600, 3600] returns {"users": 2, "identified_impressions": 3, "frequency": 1.5, "distribution": {"1": 1, "2": 1, "3+": 0}}. The impression at exactly H is outside the window.

Part 3 — Last-click attribution (ADS-430)

Goal: accept conversion events and credit each one to the campaign of the user's most recent click in the 24 hours before it.

Rules

1. ingest accepts "type": "conversion" payloads with event_id, ts, user_id (optional, same rules as Part 1), order_id (required; string or integer, normalised like other ids) and value_cents (required integer >= 0; floats and booleans are invalid). campaign_id is not required on a conversion and is ignored if present. Invalid conversions count as rejected.
2. An order is counted once: a conversion whose order_id was already ingested counts as a duplicate, even with a new event_id. Repeated event_ids are duplicates as before.
3. A click *qualifies* for a conversion at time T when it has the same (non-null) user_id and T - 86400 <= click ts <= T (both ends inclusive). Clicks from any campaign qualify. A logged-out conversion never has a qualifying click.
4. The credited click is the qualifying click with the latest ts; if several share that ts, the one with the smallest event_id (string comparison) wins. The same click can be credited by any number of conversions.
5. Attribution is computed over everything ingested so far, whatever the arrival order: a click ingested after its conversion still earns credit.
6. ["attribution_report", from_ts, to_ts] covers conversions with from_ts <= ts < to_ts (the credited click may be earlier) and returns {"campaigns": {campaign_id: {"conversions": n, "revenue_cents": n}}, "unattributed": {"conversions": n, "revenue_cents": n}}. Campaigns with no credited conversions are omitted; unattributed is always present.
7. Conversions are not ad delivery: they never change impressions, clicks, ctr, or reach.
8. hourly_report takes an optional 5th argument, an options object. With {"conversions": true}, every row also has "conversions": the number of conversions credited to this campaign whose own ts falls in that hour, and an hour that has credited conversions but no impressions or clicks gets a row with zero counts (ctr 0.0). Without the argument, or with "conversions": false, the output is exactly what it was before.

Example. u1 clicks cmp-1 at H and cmp-2 at H+1000; u1 converts at H+5000 (order_id "o-1", 2500 cents); u2 converts at H+6000 with no clicks (1000 cents); order "o-1" is reported again at H+5100 with a new event_id. The ingest returns {"accepted": 4, "duplicates": 1, "rejected": 0}, and ["attribution_report", H, H+86400] returns {"campaigns": {"cmp-2": {"conversions": 1, "revenue_cents": 2500}}, "unattributed": {"conversions": 1, "revenue_cents": 1000}}. ["hourly_report", "cmp-2", H, H+86400, {"conversions": true}] returns a row for hour H (clicks 1, conversions 0) and a row for hour H+3600 (all zeros, conversions 1).

Notes

• timeutil.py and store.py are known-good; EventStore.campaign_events ranges are [from_ts, to_ts).
• You may use the AI assistant freely. Say what you're asking it and check what it gives you.
• Later parts must not break earlier ones; hidden tests re-check Part 1 and 2 behaviour.
• The files in tests/ are not run by the grader. Use them, extend them, or ignore them.