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

.github/workflows/deploy-worker/action.yml

@@ -42,7 +42,7 @@ inputs:
     description: 'AWS_PREFIX used for config storage'
     required: true
   BUILD_UMAMI_HOST:
-    description: 'Umami analytics host URL'
+    description: 'Umami host (e.g. https://cloud.umami.is)'
     required: false
   BUILD_UMAMI_WEBSITE_ID:
     description: 'Umami analytics website ID'

.github/workflows/deploy.yml

@@ -138,6 +138,8 @@ jobs:
           mode: ${{ steps.deploy-mode.outputs.mode }}
           skip-deploy: ${{ steps.deploy-check.outputs.should-deploy == 'false' }}
           BUILD_AWS_PREFIX: ${{ vars.AWS_PREFIX }}
+          BUILD_UMAMI_HOST: ${{ vars.UMAMI_HOST }}
+          BUILD_UMAMI_WEBSITE_ID: ${{ vars.UMAMI_WEBSITE_ID }}
           origin: ${{ vars.API_ORIGIN }}
           accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

.gitignore

@@ -52,3 +52,6 @@ build
 
 # React Router
 .react-router/
+
+# Local CDN embed test harness
+cdn/public/embed-test.html

.vscode/settings.json

@@ -1,4 +1,5 @@
 {
-  "prettier.trailingComma": "none",
-  "prettier.semi": false
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "editor.formatOnSave": true,
+  "prettier.prettierPath": "node_modules/prettier/index.cjs"
 }

api/build.ts

@@ -1,9 +1,21 @@
 import { build } from 'esbuild'
 
+try {
+  process.loadEnvFile('.dev.vars')
+} catch {
+  // do nothing
+}
+
 await build({
   entryPoints: ['src/index.ts'],
   define: {
     BUILD_AWS_PREFIX: JSON.stringify(process.env.BUILD_AWS_PREFIX ?? ''),
+    BUILD_UMAMI_HOST: JSON.stringify(
+      process.env.BUILD_UMAMI_HOST || process.env.UMAMI_HOST || '',
+    ),
+    BUILD_UMAMI_WEBSITE_ID: JSON.stringify(
+      process.env.BUILD_UMAMI_WEBSITE_ID || process.env.UMAMI_WEBSITE_ID || '',
+    ),
   },
   bundle: true,
   format: 'esm',

api/package.json

@@ -7,6 +7,8 @@
     "build": "node build.ts",
     "preview": "wrangler dev",
     "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "deploy": "wrangler deploy"
   },
   "keywords": [],
@@ -35,6 +37,7 @@
     "@shared/types": "workspace:^",
     "esbuild": "0.28.0",
     "typescript": "5.9.3",
+    "vitest": "^4.1.5",
     "wrangler": "^4.87.0"
   }
 }

api/src/index.ts

@@ -5,6 +5,7 @@ import './routes/get-profile.js'
 import './routes/probabilistic-revshare.js'
 import './routes/payment/index.js'
 import './routes/wallet.js'
+import './routes/events.js'
 
 app.get('/', (c) => {
   const routes = app.routes

api/src/routes/events.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { app } from '../app.js'
+import './events.js'
+
+vi.mock('@shared/defines', () => ({
+  UMAMI_HOST: 'http://umami.test',
+  UMAMI_WEBSITE_ID: 'test-website-id',
+}))
+
+describe('POST /events', () => {
+  let fetchMock: ReturnType<typeof vi.fn>
+
+  beforeEach(() => {
+    fetchMock = vi.fn().mockResolvedValue(new Response(null, { status: 200 }))
+    vi.stubGlobal('fetch', fetchMock)
+  })
+
+  afterEach(() => {
+    vi.unstubAllGlobals()
+  })
+
+  it('forwards a valid event to Umami and returns 204', async () => {
+    const res = await app.request('/events', {
+      method: 'POST',
+      body: JSON.stringify({
+        type: 'event',
+        payload: {
+          name: 'embed.banner.click_extension_link',
+          url: '/embed/banner',
+          data: {
+            hostname: 'example.com',
+            link: 'https://example.com/install',
+          },
+        },
+      }),
+    })
+
+    expect(res.status).toBe(204)
+    expect(fetchMock).toHaveBeenCalledOnce()
+    const [url, init] = fetchMock.mock.calls[0]
+    expect(url).toBe('http://umami.test/api/send')
+    const forwarded = JSON.parse(init.body as string)
+    expect(forwarded.payload).toMatchObject({
+      website: 'test-website-id',
+      name: 'embed.banner.click_extension_link',
+      data: { hostname: 'example.com', link: 'https://example.com/install' },
+    })
+  })
+
+  it('rejects an event name without the embed. prefix with 400', async () => {
+    const res = await app.request('/events', {
+      method: 'POST',
+      body: JSON.stringify({
+        type: 'event',
+        payload: {
+          name: 'click_extension_link',
+          url: '/embed/banner',
+          data: { hostname: 'example.com' },
+        },
+      }),
+    })
+
+    expect(res.status).toBe(400)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+
+  it('rejects malformed JSON with 400', async () => {
+    const res = await app.request('/events', {
+      method: 'POST',
+      body: 'not json',
+    })
+
+    expect(res.status).toBe(400)
+    expect(fetchMock).not.toHaveBeenCalled()
+  })
+})

api/src/routes/events.ts

@@ -0,0 +1,74 @@
+import z from 'zod'
+import { UMAMI_HOST, UMAMI_WEBSITE_ID } from '@shared/defines'
+import { app } from '../app.js'
+
+const payloadSchema = z.object({
+  /** Prefixed with `embed.` to separate from frontend events */
+  name: z.string().startsWith('embed.'),
+  /** Umami "page" path, e.g. `/embed/banner` (groups events per tool) */
+  url: z.string(),
+  data: z.looseObject({
+    /** Publisher's domain from `window.location.hostname` (we can see which sites embed us) */
+    hostname: z.string(),
+  }),
+})
+
+const eventSchema = z.object({
+  type: z.literal('event'),
+  payload: payloadSchema,
+})
+
+export type EventPayload = z.infer<typeof payloadSchema>
+export type EventBody = z.infer<typeof eventSchema>
+
+app.post('/events', async ({ req, body }) => {
+  if (!UMAMI_HOST || !UMAMI_WEBSITE_ID) {
+    return body(null, 204)
+  }
+
+  let event: z.infer<typeof eventSchema>
+  try {
+    event = z.parse(eventSchema, await req.json())
+  } catch {
+    return body(null, 400)
+  }
+
+  // https://docs.umami.is/docs/enable-cloudflare-headers
+  const passthrough = [
+    'user-agent',
+    'accept-language',
+    'referer',
+    'cf-connecting-ip',
+    'cf-ipcountry',
+    'cf-ipcity',
+    'cf-region',
+    'cf-postal-code',
+    'cf-continent',
+    'cf-latitude',
+    'cf-longitude',
+    'cf-timezone',
+  ]
+  const headers = new Headers({ 'content-type': 'application/json' })
+  for (const h of passthrough) {
+    const v = req.header(h)
+    if (v) headers.set(h, v)
+  }
+
+  try {
+    await fetch(`${UMAMI_HOST}/api/send`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        ...event,
+        payload: {
+          ...event.payload,
+          website: UMAMI_WEBSITE_ID,
+        },
+      }),
+    })
+  } catch (err) {
+    console.error('umami forward failed', { name: event.payload.name }, err)
+  }
+
+  return body(null, 204)
+})

api/src/types.ts

@@ -6,6 +6,7 @@ export type {
   PaymentInitiateResult,
   PaymentStatus,
 } from './routes/payment'
+export type { EventPayload, EventBody } from './routes/events'
 
 export type ApiErrorResponse = {
   error: {

api/vitest.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['src/**/*.test.ts'],
+  },
+})

cdn/src/banner.ts

@@ -1,10 +1,12 @@
 import { API_URL } from '@shared/defines'
 import type { BannerProfile } from '@shared/types'
 import { Banner } from '@tools/components/banner'
+import { trackEventFactory } from './lib/analytics'
 import { appendPaymentPointer, fetchProfile, getScriptParams } from './utils'
 
 customElements.define('wm-banner', Banner)
 
+const trackEvent = trackEventFactory('banner')
 const params = getScriptParams('banner')
 
 appendPaymentPointer(params.walletAddress)
@@ -39,6 +41,11 @@ function drawBanner(profile: BannerProfile) {
     cdnUrl: params.cdnUrl,
   }
 
+  bannerElement.addEventListener('click-extension-link', (e) => {
+    const { link } = (e as CustomEvent<{ link: string }>).detail
+    trackEvent('click_extension_link', { link })
+  })
+
   const position = profile.position ? profile.position.toLowerCase() : 'bottom'
 
   bannerElement.style.position = 'fixed'

cdn/src/lib/analytics.ts

@@ -0,0 +1,22 @@
+import type { EventBody, EventPayload } from 'publisher-tools-api'
+import { API_URL } from '@shared/defines'
+import type { Tool } from '@shared/types'
+
+type EventData = Omit<EventPayload['data'], 'hostname'>
+
+export function trackEventFactory(tool: Tool) {
+  const hostname = window.location.hostname
+
+  return (name: string, data?: EventData): void => {
+    if (!API_URL) return
+    const body: EventBody = {
+      type: 'event',
+      payload: {
+        name: `embed.${tool}.${name}`,
+        url: `/embed/${tool}`,
+        data: { hostname, ...data },
+      },
+    }
+    navigator.sendBeacon?.(`${API_URL}/events`, JSON.stringify(body))
+  }
+}

cdn/src/utils/offerwall/WebMonetizationCustomOfferwallChoice.ts

@@ -19,6 +19,9 @@ import type {
   OfferwallCustomChoice,
   StoredEvent,
 } from './types'
+import { trackEventFactory } from '../../lib/analytics'
+
+const trackEvent = trackEventFactory('offerwall')
 
 export class WebMonetizationCustomOfferwallChoice implements OfferwallCustomChoice {
   #browserSupportKey = getBrowserSupportForExtension(
@@ -98,8 +101,8 @@ export class WebMonetizationCustomOfferwallChoice implements OfferwallCustomChoi
 
     const owElem = document.createElement(elementName) as OfferwallModal
     const actions = owElem.setController({
-      onExtensionLinkClick() {
-        // can start tracking
+      onExtensionLinkClick(e) {
+        trackEvent('click_extension_link', { link: e.detail.link })
       },
       onModalClose() {
         abortController.abort('modal closed by user')

components/src/banner.ts

@@ -62,7 +62,11 @@ export class Banner extends LitElement {
   }
 
   private handleLinkClick() {
-    // TODO: do anything other than open the link in a new tab, like analytics, showing some thank you message etc.
+    this.dispatchEvent(
+      new CustomEvent('click-extension-link', {
+        detail: { link: this.extensionUrl },
+      }),
+    )
   }
 
   /**

components/src/offerwall/components/install-required.ts

@@ -95,6 +95,7 @@ export class InstallRequired extends LitElement {
   #onExtensionLinkClick = (ev: MouseEvent) => {
     const event = new CustomEvent('click-extension-link', {
       cancelable: true,
+      detail: { link: this.extensionUrl },
     })
     this.dispatchEvent(event)
     if (event.defaultPrevented) {

components/src/offerwall/controller.ts

@@ -1,8 +1,10 @@
 export type Screen = 'install-required' | 'contribution-required' | 'all-set'
 
+export type ExtensionLinkClickEvent = CustomEvent<{ link: string }>
+
 export interface Controller {
   onModalClose(ev: Event): void
-  onExtensionLinkClick(ev: Event): void
+  onExtensionLinkClick(ev: ExtensionLinkClickEvent): void
   onDone(ev: Event): void
   /**
    * In preview mode, instead of rendering the component as "dialog" modal;  we

components/src/offerwall/index.ts

@@ -8,7 +8,12 @@ import {
   InstallRequired,
 } from './components/index.js'
 import { NO_OP_CONTROLLER } from './controller.js'
-import type { Actions, Controller, Screen } from './controller.js'
+import type {
+  Actions,
+  Controller,
+  ExtensionLinkClickEvent,
+  Screen,
+} from './controller.js'
 import styles from './styles.css?raw'
 import styleTokens from './vars.css?raw'
 
@@ -115,7 +120,7 @@ export class OfferwallModal extends LitElement {
     this.#closeDialog()
   }
 
-  #onExtensionLinkClick = (ev: Event) => {
+  #onExtensionLinkClick = (ev: ExtensionLinkClickEvent) => {
     this.#controller.onExtensionLinkClick(ev)
     if (ev.defaultPrevented) return
   }