feat(analytics): add click extension link event tracking for banner and offerwall by kjmitchelljr · Pull Request #683 · interledger/publisher-tools

kjmitchelljr · 2026-04-23T21:39:37Z

Summary

Adds embed.click_link_banner and embed.click_link_offerwall event tracking when visitors click "Install the Web Monetization Extension" in the banner or offerwall embeds. Events are proxied CDN → API → Umami

Implementation

api/src/routes/events.ts — POST /events proxy: validates event name, injects website/hostname from env, forwards to Umami
cdn/src/lib/analytics.ts — builds the Umami payload and sends via navigator.sendBeacon
components/src/banner.ts + offerwall install-required screen — dispatch click-extension-link with { link }

Follow Ups

Origin allow-list + rate limit on /events

Part of

#625 / #682

Three small departures from your original:

This reverts commit 51274ac.

github-actions · 2026-04-23T21:40:53Z

Deployment results

Worker	Alias	URL	Outcome
API	-	3b3db205	success
CDN	-	868c9342	success
App	-	24449f9d	success

Logs #25474495805

kjmitchelljr · 2026-04-23T21:41:50Z

+type ClickLinkEvent = `click_link_${ExtensionLinkSource}`
+
+export type CdnEventMap = {
+  [K in ClickLinkEvent]: undefined


Should the event payload include { link: string } (the resolved extension store URL) to allow slicing by browser/store in the dashboard or is the tracking from Posthog fine on this front?

sidvishnoi

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.

sidvishnoi

Moving in right direction now..

sidvishnoi · 2026-05-01T09:05:42Z

+        'Content-Type': 'application/json',
+        'User-Agent': req.header('user-agent') ?? '',
+        'X-Forwarded-For': req.header('cf-connecting-ip') ?? '', // do we need this?


We might want to pass through most of the headers here, not just these.

Still debating whether to just pass-through all here. Went with allowlist that made sense to me, but we could include more. Let me know your thoughts.

Umami docs shows these headers: https://docs.umami.is/docs/enable-cloudflare-headers
I think we want to skip the Host as headers for sure, but we do want to pass through the website domain to be available in our event payload/data, so we know which sites are embedding our tools.

…k in metadata

kjmitchelljr · 2026-05-07T03:19:33Z

+          payload: {
+            ...event.payload,
+            website: env.UMAMI_WEBSITE_ID,
+            hostname: env.UMAMI_HOSTNAME,


@DarianM @sidvishnoi would you be able to provide clarity on where the environment variables are kept? Would need to have one for UMAMI_HOSTNAME if I understand correctly, but please feel free to provide more insight

Replied here: #683 (comment)

These build time vars are stored in https://github.com/interledger/publisher-tools/settings/variables/actions

sidvishnoi

Nearly there, but little broken..

sidvishnoi · 2026-05-07T12:32:12Z

+export function trackEvent(event: TrackArgs): void {
+  if (!API_URL) return
+  // assumes all event names follow 'embed.click_link_<source>'
+  const url = `/embed/${event.name.replace('embed.click_link_', '')}`


Alternative: How about we use a higher-order function like this:

export function trackEventFactory(tool: Tool) { return (event: TrackArgs) => { // ... } } const trackEvent = trackEventFactory('banner') // at some top-level in each of our tool script in CDN trackEvent({name, /* ... */ })

sidvishnoi · 2026-05-07T12:33:06Z

+      onExtensionLinkClick(e) {
+        const { link } = (e as CustomEvent<{ link: string }>).detail


Nit: Let's update the Controller interface to denote what the type of e is.

sidvishnoi · 2026-05-07T12:37:41Z

+  UMAMI_HOST?: string
+  UMAMI_WEBSITE_ID?: string
+  UMAMI_HOSTNAME?: string


These 3 won't be available in env vars, but rather available as build time vars:

publisher-tools/api/build.ts

Lines 5 to 7 in 8e215c8

define: {

BUILD_AWS_PREFIX: JSON.stringify(process.env.BUILD_AWS_PREFIX ?? ''),

},

Then, we'd use them via @shared/defines:

publisher-tools/api/src/index.ts

Line 1 in 8e215c8

import { AWS_PREFIX } from '@shared/defines'

Would need to update CI a bit as well:

publisher-tools/.github/workflows/deploy.yml

Line 140 in 8e215c8

BUILD_AWS_PREFIX: ${{ vars.AWS_PREFIX }}

sidvishnoi · 2026-05-07T12:39:05Z

+  UMAMI_HOST?: string
+  UMAMI_WEBSITE_ID?: string
+  UMAMI_HOSTNAME?: string


Nit: Maybe call it UMAMI_API_HOST

sidvishnoi · 2026-05-07T12:40:12Z

+import type { TrackFn } from 'publisher-tools-api'
+import { API_URL } from '@shared/defines'
+
+type TrackArgs = Omit<TrackFn, 'url'>


Perhaps call TrackFn as something like: TrackPayload?

sidvishnoi · 2026-05-07T12:52:33Z

+  const blob = new Blob(
+    [JSON.stringify({ type: 'event', payload: { ...event, url } })],
+    { type: 'text/plain' },
+  )
+  navigator.sendBeacon?.(`${API_URL}/events`, blob)


This gave me a HTTP 400 validation error as I used the PR preview as well as checked out locally.

{ "error": { "message": "Validation failed", "code": "VALIDATION_ERROR", "details": { "issues": [ { "path": "type", "message": "Invalid input: expected \"event\"", "code": "invalid_value" }, { "path": "payload", "message": "Invalid input", "code": "invalid_union" } ] } } }

I think it could be because we're sending text/plain, but server validator is validating on zValidator('json', schema)`?

This worked locally:

diff --git a/api/src/routes/events.ts b/api/src/routes/events.ts index 582bcfff..163f1278 100644 --- a/api/src/routes/events.ts +++ b/api/src/routes/events.ts @@ -24,14 +24,13 @@ export type TrackFn = z.infer<typeof payloadSchema> app.post( '/events', - zValidator('json', eventSchema), async ({ req, env, body }) => { + const event = z.parse(eventSchema, await req.json()) + if (!env.UMAMI_HOST || !env.UMAMI_WEBSITE_ID || !env.UMAMI_HOSTNAME) { return body(null, 204) } - const event = req.valid('json') - const headers = new Headers({ 'content-type': 'application/json' }) for (const h of ['user-agent', 'accept-language', 'referer']) { const v = req.header(h)

kjmitchelljr added 16 commits April 15, 2026 15:05

feat(analytics): add tools event tracking and shared event constants

6579ea8

Merge branch 'main' into feat/663-tools-analytics-events

118e943

Resolve pnpm lockfile

3dd8b6a

Merge branch 'main' into feat/663-tools-analytics-events

95649ef

removed shared analytics and made TrackFn constrained to ToolsEventMap

f5b43de

resolve pnpm lockfile

613f985

use id instead of authServer for wallet provider capture

5b8bc1c

Add simple tracking for fields changed

51274ac

Merge branch 'main' into feat/663-tools-analytics-events

db4fd66

Revert "Add simple tracking for fields changed"

100df55

This reverts commit 51274ac.

Remove tools prefix

28ae2bc

Merge branch 'main' into feat/663-tools-analytics-events

4613aa0

Remove tool settings and update link tag tracking

598f8e9

Tool name added to event

5dcc993

Merge branch 'main' into feat/663-tools-analytics-events

5890bda

Add analytic tracking for extension link clicks on banner and offerwall

9621e4a

kjmitchelljr temporarily deployed to staging April 23, 2026 21:39 — with GitHub Actions Inactive

kjmitchelljr changed the base branch from main to feat/663-tools-analytics-events April 23, 2026 21:40

kjmitchelljr commented Apr 23, 2026

View reviewed changes

kjmitchelljr temporarily deployed to staging April 23, 2026 21:41 — with GitHub Actions Inactive

kjmitchelljr requested review from DarianM and sidvishnoi April 23, 2026 21:41

kjmitchelljr added 2 commits April 23, 2026 17:49

prettier fix

8e74ad4

lint fix

6a750ba

sidvishnoi requested changes Apr 24, 2026

View reviewed changes

Comment thread cdn/src/lib/analytics.ts Outdated

sidvishnoi temporarily deployed to staging April 24, 2026 02:03 — with GitHub Actions Inactive

Clean up code - don't need to match frontend as much

6827127

kjmitchelljr temporarily deployed to staging April 24, 2026 02:15 — with GitHub Actions Inactive

Merge branch 'main' into feat/663-tools-analytics-events

81753d0

kjmitchelljr temporarily deployed to staging April 28, 2026 15:18 — with GitHub Actions Inactive

feat(analytics): proxy CDN extension-link clicks to Umami via API

e0c0f6a

kjmitchelljr temporarily deployed to staging April 30, 2026 02:36 — with GitHub Actions Inactive

kjmitchelljr requested a review from sidvishnoi April 30, 2026 02:41

sidvishnoi requested changes May 1, 2026

View reviewed changes

sidvishnoi temporarily deployed to staging May 1, 2026 09:09 — with GitHub Actions Inactive

sidvishnoi temporarily deployed to staging May 1, 2026 11:04 — with GitHub Actions Inactive

Merge branch 'main' into feat/682-cdn-analytics-events

132294d

kjmitchelljr temporarily deployed to staging May 6, 2026 21:44 — with GitHub Actions Inactive

feat(analytics): proxy Umami payload andinclude url and extension lin…

6858838

…k in metadata

kjmitchelljr temporarily deployed to staging May 7, 2026 03:06 — with GitHub Actions Inactive

kjmitchelljr temporarily deployed to staging May 7, 2026 03:09 — with GitHub Actions Inactive

kjmitchelljr temporarily deployed to staging May 7, 2026 03:12 — with GitHub Actions Inactive

kjmitchelljr temporarily deployed to staging May 7, 2026 03:13 — with GitHub Actions Inactive

kjmitchelljr temporarily deployed to staging May 7, 2026 03:14 — with GitHub Actions Inactive

kjmitchelljr temporarily deployed to staging May 7, 2026 03:15 — with GitHub Actions Inactive

Resolve prettier issue

9db44cd

kjmitchelljr temporarily deployed to staging May 7, 2026 03:16 — with GitHub Actions Inactive

kjmitchelljr requested a review from sidvishnoi May 7, 2026 03:17

kjmitchelljr commented May 7, 2026

View reviewed changes

kjmitchelljr temporarily deployed to staging May 7, 2026 03:19 — with GitHub Actions Inactive

set prettier path for pnpm

8e215c8

kjmitchelljr temporarily deployed to staging May 7, 2026 03:30 — with GitHub Actions Inactive

sidvishnoi requested changes May 7, 2026

View reviewed changes

sidvishnoi temporarily deployed to staging May 7, 2026 12:53 — with GitHub Actions Inactive

sidvishnoi temporarily deployed to staging May 7, 2026 12:55 — with GitHub Actions Inactive

sidvishnoi temporarily deployed to staging May 7, 2026 12:59 — with GitHub Actions Inactive

sidvishnoi temporarily deployed to staging May 7, 2026 13:02 — with GitHub Actions Inactive

sidvishnoi temporarily deployed to staging May 7, 2026 13:05 — with GitHub Actions Inactive

		onExtensionLinkClick(e) {
		const { link } = (e as CustomEvent<{ link: string }>).detail

	define: {
	BUILD_AWS_PREFIX: JSON.stringify(process.env.BUILD_AWS_PREFIX ?? ''),
	},

Conversation

kjmitchelljr commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation

Follow Ups

Part of

Uh oh!

github-actions Bot commented Apr 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Deployment results

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sidvishnoi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

sidvishnoi May 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

kjmitchelljr commented Apr 23, 2026 •

edited

Loading

github-actions Bot commented Apr 23, 2026 •

edited

Loading

sidvishnoi May 7, 2026 •

edited

Loading