feat(tracking): suppress Apple MPP opens and bot click prefetches#50
Open
jusso-dev wants to merge 1 commit into
Open
feat(tracking): suppress Apple MPP opens and bot click prefetches#50jusso-dev wants to merge 1 commit into
jusso-dev wants to merge 1 commit into
Conversation
…oses #31) Apple Mail Privacy Protection prefetches the open pixel, and security gateways like Mimecast / Proofpoint / Barracuda HEAD or GET the click URL seconds after delivery. Both inflate metrics and produce false clicked_at timestamps on campaign targets. A new `lib/tracking/bot-detection.ts` provides: - `detectAppleMailPrivacyProtection({ userAgent, ip })` — matches Apple Mail UA strings and iCloud Private Relay egress ranges. - `detectBotClick({ userAgent, method, isBot, sentAt })` — matches HEAD requests, headless / scanner UAs, and clicks within 1.5s of sentAt (the gateway prefetch window). `recordTrackingEvent` now accepts a `suppressionDecision` callback that runs after the campaign target is loaded. When suppression fires we still insert the events row tagged with `unverified: true` or `bot: true` and the reason, but we skip the `campaignTargets.openedAt / clickedAt` write and the SIEM/SOAR push. The dashboards (which read those target timestamps) therefore stop counting bot traffic by default, while the underlying hits remain available for forensics.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Closes #31. Stops Apple Mail Privacy Protection and security-gateway URL scanners from polluting open/click metrics.
lib/tracking/bot-detection.ts:detectAppleMailPrivacyProtection({ userAgent, ip })— matches Apple Mail UA strings and a snapshot of iCloud Private Relay egress ranges (operator-refreshable frommask-api.icloud.com/egress-ip-ranges.csv).detectBotClick({ userAgent, method, isBot, sentAt })— flags HEAD requests, headless / scanner UAs (curl, wget, python-requests, Mimecast, Proofpoint URLDefense, etc.),agent.isBot, and clicks within 1.5s ofsentAt.recordTrackingEventnow takes asuppressionDecisioncallback that runs after the campaign target is loaded so the click route can seesentAtfor the prefetch-window check.eventsrow is still inserted, taggedunverified: true(pixel) orbot: true(click) plus asuppressionReasonfor forensics.campaignTargets.openedAt/clickedAtare NOT written, so dashboards stop counting these./p/[...token]) and click route (/c/[token]) wired up.Test plan
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko)→ event row exists withunverified: true,campaignTargets.openedAtstays NULL.sentAt→ event row taggedbot: true, suppressionReason: "prefetch_window",campaignTargets.clickedAtstays NULL.curl -X HEAD /c/<token>→ taggedhead_request, no clickedAt write.https://claude.ai/code/session_01PiiqDRQJdW1sBLvEmZ3GBC
Generated by Claude Code