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

.github/workflows/deploy.yml

@@ -153,6 +153,8 @@ jobs:
           build: 'pnpm -C cdn run build'
           BUILD_API_URL: ${{ steps.api.outputs.url }}
           BUILD_AWS_PREFIX: ${{ vars.AWS_PREFIX }}
+          BUILD_UMAMI_HOST: ${{ vars.UMAMI_HOST }}
+          BUILD_UMAMI_WEBSITE_ID: ${{ vars.UMAMI_WEBSITE_ID }}
           origin: ${{ vars.CDN_ORIGIN }}
           accountId: ${{ vars.CLOUDFLARE_ACCOUNT_ID }}
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

cdn/@types/index.d.ts

@@ -6,4 +6,10 @@ declare global {
     'wm-banner': Banner
     'wm-payment-widget': PaymentWidget
   }
+
+  interface Window {
+    umami?: {
+      track(eventName: string, eventData?: Record<string, unknown>): void
+    }
+  }
 }

cdn/build.js

@@ -21,6 +21,12 @@ await build({
   treeShaking: true,
   define: {
     BUILD_API_URL: JSON.stringify(process.env.BUILD_API_URL ?? ''),
+    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 || '',
+    ),
   },
   assetNames: 'assets/[ext]/[name]-[hash]',
   loader: {

cdn/src/banner.ts

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

cdn/src/lib/analytics.ts

@@ -0,0 +1,39 @@
+import { UMAMI_HOST, UMAMI_WEBSITE_ID } from '@shared/defines'
+
+type ExtensionLinkSource = 'banner' | 'offerwall'
+type ClickLinkEvent = `click_link_${ExtensionLinkSource}`
+
+export type CdnEventMap = {
+  [K in ClickLinkEvent]: undefined
+}
+
+type TrackArgs<E extends keyof CdnEventMap> = CdnEventMap[E] extends undefined
+  ? [eventName: E]
+  : [eventName: E, data: CdnEventMap[E]]
+
+let umamiInjected = false
+
+/**
+ * Appended the Umami tracker script so it's loaded before any
+ * trackEvent() call fires (avoids a race on the first user interaction).
+ */
+export function injectUmami() {
+  if (!UMAMI_HOST || !UMAMI_WEBSITE_ID) return
+  if (typeof window === 'undefined' || typeof document === 'undefined') return
+  if (window.umami || umamiInjected) return
+
+  umamiInjected = true
+  const script = document.createElement('script')
+  script.defer = true
+  script.src = `${UMAMI_HOST}/script.js`
+  script.setAttribute('data-website-id', UMAMI_WEBSITE_ID)
+  document.head.appendChild(script)
+}
+
+export function trackEvent<E extends keyof CdnEventMap>(
+  ...args: TrackArgs<E>
+): void {
+  const [eventName, data] = args as [E, CdnEventMap[E] | undefined]
+  injectUmami()
+  window.umami?.track(eventName, data)
+}

cdn/src/offerwall.ts

@@ -1,5 +1,6 @@
 import { API_URL } from '@shared/defines'
 import { OfferwallModal } from '@tools/components'
+import { injectUmami } from './lib/analytics'
 import { appendPaymentPointer, fetchProfile, getScriptParams } from './utils'
 import {
   WebMonetizationCustomOfferwallChoice,
@@ -9,6 +10,7 @@ import {
 
 const NAME = 'wm-offerwall'
 customElements.define(NAME, OfferwallModal)
+injectUmami()
 
 const params = getScriptParams('offerwall')
 const linkElem = appendPaymentPointer(params.walletAddress)

cdn/src/utils/offerwall/WebMonetizationCustomOfferwallChoice.ts

@@ -19,6 +19,7 @@ import type {
   OfferwallCustomChoice,
   StoredEvent,
 } from './types'
+import { trackEvent } from '../../lib/analytics'
 
 export class WebMonetizationCustomOfferwallChoice implements OfferwallCustomChoice {
   #browserSupportKey = getBrowserSupportForExtension(
@@ -99,7 +100,7 @@ export class WebMonetizationCustomOfferwallChoice implements OfferwallCustomChoi
     const owElem = document.createElement(elementName) as OfferwallModal
     const actions = owElem.setController({
       onExtensionLinkClick() {
-        // can start tracking
+        trackEvent('click_link_offerwall')
       },
       onModalClose() {
         abortController.abort('modal closed by user')

components/src/banner.ts

@@ -62,7 +62,12 @@ 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', {
+        bubbles: true,
+        composed: true,
+      }),
+    )
   }
 
   /**

frontend/app/components/redesign/components/LinkTagGenerator.tsx

@@ -6,6 +6,7 @@ import {
   validateAndConfirmPointer,
   WalletAddressFormatError,
 } from '@shared/utils/index'
+import { useTrackEvent } from '~/lib/analytics'
 
 const htmlEncodePointer = (pointer: string): string => {
   return pointer
@@ -24,6 +25,7 @@ export const LinkTagGenerator = () => {
   const [error, setError] = useState('')
   const [showCodeBox, setShowCodeBox] = useState(false)
   const [isCopied, setIsCopied] = useState(false)
+  const trackEvent = useTrackEvent()
 
   const handleSubmit = useCallback(
     async (e: React.FormEvent) => {
@@ -36,6 +38,9 @@ export const LinkTagGenerator = () => {
         const validatedPointer = await validateAndConfirmPointer(pointerInput)
         setParsedLinkTag(htmlEncodePointer(validatedPointer))
         setShowCodeBox(true)
+        trackEvent('link_tag_generated', {
+          wallet_provider: new URL(validatedPointer).hostname,
+        })
       } catch (err) {
         const message =
           err instanceof WalletAddressFormatError
@@ -47,7 +52,7 @@ export const LinkTagGenerator = () => {
         setIsLoading(false)
       }
     },
-    [pointerInput],
+    [pointerInput, trackEvent],
   )
 
   const handleOnChange = useCallback(

frontend/app/components/redesign/components/ToolsWalletAddress.tsx

@@ -61,14 +61,21 @@ export const ToolsWalletAddress = ({
       const walletAddressInfo = await getWalletAddress(walletAddressUrl)
       walletActions.setWalletAddressId(walletAddressInfo.id)
       await connect()
-      trackEvent('wallet_connected')
+      trackEvent('wallet_connected', {
+        wallet_provider: new URL(walletAddressInfo.id).hostname,
+      })
     } catch (error) {
       setError({ walletAddress: [(error as Error).message] })
     } finally {
       setIsLoading(false)
     }
   }
 
+  const handleDisconnect = () => {
+    trackEvent('wallet_disconnected')
+    disconnect()
+  }
+
   const handleWalletAddressChange = (
     e: React.ChangeEvent<HTMLInputElement>,
   ) => {
@@ -160,7 +167,7 @@ export const ToolsWalletAddress = ({
           </div>
           {snap.isWalletConnected && (
             <button
-              onClick={disconnect}
+              onClick={handleDisconnect}
               className="flex items-center justify-center w-12 h-12 p-2 rounded-lg shrink-0 hover:bg-gray-50 active:bg-gray-100 transition-colors"
               aria-label="Disconnect wallet"
             >

frontend/app/hooks/useSaveProfile.tsx

@@ -6,6 +6,7 @@ import {
 } from '@/components'
 import { TOOL_BANNER, TOOL_OFFERWALL, TOOL_WIDGET } from '@shared/types'
 import { useDialog } from '~/hooks/useDialog'
+import { useTrackEvent } from '~/lib/analytics'
 import { ApiError } from '~/lib/helpers'
 import { actions as bannerActions } from '~/stores/banner-store'
 import { actions as offerwallActions } from '~/stores/offerwall-store'
@@ -28,6 +29,7 @@ function getToolActions() {
 
 export const useSaveProfile = (wallet: WalletStore) => {
   const [openDialog, closeDialog] = useDialog()
+  const trackEvent = useTrackEvent()
 
   const save = useCallback(
     async (action: 'save-success' | 'script'): Promise<void> => {
@@ -48,10 +50,13 @@ export const useSaveProfile = (wallet: WalletStore) => {
 
         if (result.success) {
           actions.commitProfile()
+          const tool = toolState.currentToolType
 
           if (action === 'script') {
+            trackEvent(`${tool}_script_generated`)
             openDialog(<ScriptDialog wallet={wallet} />)
           } else {
+            trackEvent(`${tool}_profile_saved`)
             openDialog(<StatusDialog onDone={closeDialog} />)
           }
         }
@@ -69,7 +74,7 @@ export const useSaveProfile = (wallet: WalletStore) => {
         )
       }
     },
-    [openDialog, closeDialog],
+    [openDialog, closeDialog, trackEvent],
   )
 
   const saveLastAction = useCallback(async (): Promise<void> => {

frontend/app/lib/analytics-events.ts

@@ -0,0 +1,13 @@
+import type { Tool } from '@shared/types'
+
+type ProfileSavedEvent = `${Tool}_profile_saved`
+type ScriptGeneratedEvent = `${Tool}_script_generated`
+
+export type ToolsEventMap = {
+  click_card_tool: { link: string }
+  wallet_connected: { wallet_provider: string }
+  wallet_disconnected: undefined
+  link_tag_generated: { wallet_provider: string }
+} & {
+  [K in ProfileSavedEvent | ScriptGeneratedEvent]: undefined
+}

frontend/app/lib/analytics.tsx

@@ -2,10 +2,12 @@ import { createContext, useCallback, useContext } from 'react'
 import type { ReactNode } from 'react'
 import { useLocation } from 'react-router'
 import { TOOLS } from '@shared/types'
+import type { ToolsEventMap } from '~/lib/analytics-events'
 
-type TrackFn = (
-  eventName: string,
-  eventData?: Record<string, string | number | boolean | null>,
+export type TrackFn = <E extends keyof ToolsEventMap>(
+  ...args: ToolsEventMap[E] extends undefined
+    ? [eventName: E]
+    : [eventName: E, data: ToolsEventMap[E]]
 ) => void
 
 const TrackContext = createContext<TrackFn>(() => {})
@@ -14,12 +16,13 @@ export function TelemetryProvider({ children }: { children: ReactNode }) {
   const { pathname } = useLocation()
   const tool = TOOLS.find((t) => pathname.startsWith(`/${t}`))
 
-  const track = useCallback<TrackFn>(
-    (eventName, eventData) => {
-      window.umami?.track(eventName, tool ? { tool, ...eventData } : eventData)
-    },
+  const track = useCallback(
+    ((eventName, eventData) => {
+      window.umami?.track(eventName, { ...(tool && { tool }), ...eventData })
+    }) as TrackFn,
     [tool],
   )
+
   return <TrackContext.Provider value={track}>{children}</TrackContext.Provider>
 }