Skip to content

feat(analytics): add click extension link event tracking for banner and offerwall#683

Open
kjmitchelljr wants to merge 44 commits into
mainfrom
feat/682-cdn-analytics-events
Open

feat(analytics): add click extension link event tracking for banner and offerwall#683
kjmitchelljr wants to merge 44 commits into
mainfrom
feat/682-cdn-analytics-events

Conversation

@kjmitchelljr
Copy link
Copy Markdown
Collaborator

@kjmitchelljr kjmitchelljr commented Apr 23, 2026

Summary

Adds embed.{tool}.click_extension_link event tracking when visitors click "Install the Web Monetization Extension" in the banner or offerwall embeds

Architecture

  • CDN (navigator.sendBeacon) → POST /events on the API
  • API validates the event name (embed.* prefix), forwards to Umami's /api/send with publisher's geo headers (per Umami's CF docs)
  • Schema (api/src/routes/events.ts) exports EventPayload (inner payload) and
    EventBody (full envelope); CDN imports both so request bodies stay in sync with the server schema
  • trackEventFactory(tool) captures host context once per script entry; returned trackEvent(name, data?) takes
    positional args

Follow Ups

  • Origin allow-list + rate limit on /events

Part of

#625 / #682

Three small departures from your original:

@kjmitchelljr kjmitchelljr changed the base branch from main to feat/663-tools-analytics-events April 23, 2026 21:40
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Apr 23, 2026

Deployment results

Worker Alias URL Outcome
API - f0574e32 success
CDN - a3f2f884 success
App - 0e957cd5 success

Logs #25825486362

Comment thread cdn/src/lib/analytics.ts Outdated
Copy link
Copy Markdown
Member

@sidvishnoi sidvishnoi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This will end up injecting umami into the website. It'll track the website's page views etc. Also, what if the site already has umami? Which window.track() will get used? Also, what if site's CSP doesn't allow unami script/API?

We should instead proxy the events from CDN to go via a custom endpoint in API. That'll mean calling umami API from our API, and not using umami script.

Comment thread cdn/src/lib/analytics.ts Outdated
@kjmitchelljr
Copy link
Copy Markdown
Collaborator Author

@sidvishnoi All the changes should be there now, adding in small test for POST, but wanted to ask about the Github Actions variables, right now I'm not seeing UMAMI related vars unless that is something still to add

Copy link
Copy Markdown
Member

@sidvishnoi sidvishnoi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nearly there!

Comment thread .github/workflows/deploy-worker/action.yml Outdated
Comment thread api/src/routes/events.ts Outdated
Comment thread api/src/routes/events.ts Outdated
Comment thread api/src/routes/events.ts Outdated
Comment thread api/src/routes/events.test.ts
Comment thread cdn/src/lib/analytics.ts Outdated
Comment thread cdn/src/lib/analytics.ts Outdated
Copy link
Copy Markdown
Member

@sidvishnoi sidvishnoi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Two small details left. Rest is good!

Comment thread api/src/routes/events.ts
...event,
payload: {
...event.payload,
website: UMAMI_WEBSITE_ID,
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's also add a tag for events from embeds.

Suggested change
website: UMAMI_WEBSITE_ID,
website: UMAMI_WEBSITE_ID,
tag: 'embed',

Comment thread cdn/src/lib/analytics.ts
Comment on lines +14 to +18
payload: {
name: `embed.${tool}.${name}`,
url: `/embed/${tool}`,
data: { hostname, ...data },
},
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Compared to umami.track(), we're missing the screen size details.
https://docs.umami.is/docs/tracker-functions#pageviews

Perhaps we should add it manually.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants