feat(frontend): set up Umami for events data collection (#651)

Author: DarianM

.env.sample

@@ -11,3 +11,7 @@ AWS_ACCESS_KEY_ID="AWS_KEY_ID"
 AWS_SECRET_ACCESS_KEY="AWS_SECRET_KEY"
 AWS_S3_ENDPOINT="http://localhost:8081" # for dev
 # AWS_S3_ENDPOINT="https://bucket-name.s3.bucket-region.amazonaws.com" # when using AWS
+
+# Umami Analytics
+UMAMI_HOST="http://localhost:8082" # for dev
+UMAMI_WEBSITE_ID="<your-website-uuid>"

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

@@ -44,6 +44,12 @@ inputs:
   BUILD_AWS_PREFIX:
     description: 'AWS_PREFIX used for config storage'
     required: true
+  BUILD_UMAMI_HOST:
+    description: 'Umami analytics host URL'
+    required: false
+  BUILD_UMAMI_WEBSITE_ID:
+    description: 'Umami analytics website ID'
+    required: false
 
 outputs:
   url:
@@ -68,6 +74,8 @@ runs:
         BUILD_API_URL: ${{ inputs.BUILD_API_URL }}
         BUILD_CDN_URL: ${{ inputs.BUILD_CDN_URL }}
         BUILD_AWS_PREFIX: ${{ inputs.BUILD_AWS_PREFIX }}
+        BUILD_UMAMI_HOST: ${{ inputs.BUILD_UMAMI_HOST }}
+        BUILD_UMAMI_WEBSITE_ID: ${{ inputs.BUILD_UMAMI_WEBSITE_ID }}
 
     - name: Get worker deploy command
       if: ${{ inputs.skip-deploy == 'false' && (inputs.changed == 'true' || inputs.mode == 'production') }}

.github/workflows/deploy.yml

@@ -170,6 +170,8 @@ jobs:
           BUILD_API_URL: ${{ steps.api.outputs.url }}
           BUILD_CDN_URL: ${{ steps.cdn.outputs.url }}
           BUILD_AWS_PREFIX: ${{ vars.AWS_PREFIX }}
+          BUILD_UMAMI_HOST: ${{ vars.UMAMI_HOST }}
+          BUILD_UMAMI_WEBSITE_ID: ${{ vars.UMAMI_WEBSITE_ID }}
           stagingUrl: ${{ vars.APP_STAGING_URL }}
           productionUrl: ${{ vars.APP_PRODUCTION_URL }}
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

.vscode/tasks.json

@@ -57,6 +57,20 @@
         "group": "frontend"
       }
     },
+    {
+      "label": "Run Analytics",
+      "type": "shell",
+      "command": "pnpm analytics:start",
+      "hide": true,
+      "runOptions": {
+        "instanceLimit": 1,
+        "instancePolicy": "terminateOldest"
+      },
+      "presentation": {
+        "revealProblems": "onProblem",
+        "group": "localenv"
+      }
+    },
     {
       "label": "Dev",
       "icon": {
@@ -78,7 +92,13 @@
         "reveal": "always",
         "showReuseMessage": true
       },
-      "dependsOn": ["Run Local S3", "Run CDN", "Run API", "Run Editor UI"]
+      "dependsOn": [
+        "Run Local S3",
+        "Run CDN",
+        "Run API",
+        "Run Editor UI",
+        "Run Analytics"
+      ]
     }
   ]
 }

docs/env-vars.md

@@ -20,6 +20,8 @@ Then, edit the `.dev.vars` file to set the required values as described below.
 | `AWS_ACCESS_KEY_ID`     | AWS access key for S3. Not used in local dev.    | `ABCDEFGHIJKLMN12OPQR`                       |
 | `AWS_SECRET_ACCESS_KEY` | AWS secret key for S3. Not used in local dev.    | `ab1cD/2e/fGhIJ11kL13mN0pQrS45tu6V7w8X9yZ`   |
 | `AWS_S3_ENDPOINT`       | The endpoint for the S3-compatible storage.      | `http://localhost:8081`                      |
+| `UMAMI_HOST`            | URL of your Umami instance.                      | `http://localhost:8082`                      |
+| `UMAMI_WEBSITE_ID`      | Website ID from the Umami dashboard.             | `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`       |
 
 ## Detailed Configuration
 
@@ -123,6 +125,22 @@ AWS_S3_ENDPOINT="https://your-bucket-name.s3.your-region.amazonaws.com"
 
 </details>
 
+### Umami Analytics
+
+Optional. If unset, the analytics script is silently skipped.
+For local dev, start the Umami instance first:
+
+```sh
+cd localenv/analytics && docker compose up -d
+```
+
+Then log in at `http://localhost:8082` (default credentials: `admin` / `umami`), go to Settings → Websites → Add website, and copy the **Website ID**.
+
+```
+UMAMI_HOST="http://localhost:8082"
+UMAMI_WEBSITE_ID="<your-website-id>"
+```
+
 ## Development vs Production
 
 ### Development Setup

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

@@ -9,6 +9,7 @@ import {
 } from '@shared/utils'
 import { SVGRefresh, SVGSpinner } from '~/assets/svg'
 import { useConnectWallet } from '~/hooks/useConnectWallet'
+import { useTrackEvent } from '~/lib/analytics'
 import type { ElementErrors } from '~/lib/types'
 import { useUIActions } from '~/stores/uiStore'
 import type { WalletActions, WalletStore } from '~/stores/wallet-store'
@@ -26,6 +27,7 @@ export const ToolsWalletAddress = ({
 }: Props) => {
   const { connect, disconnect } = useConnectWallet(snap, walletActions)
   const uiActions = useUIActions()
+  const trackEvent = useTrackEvent()
   const [error, setError] = useState<ElementErrors>()
   const [isLoading, setIsLoading] = useState(false)
   const inputRef = useRef<HTMLInputElement>(null)
@@ -63,6 +65,7 @@ export const ToolsWalletAddress = ({
       const walletAddressInfo = await getWalletAddress(walletAddressUrl)
       walletActions.setWalletAddressId(walletAddressInfo.id)
       await connect()
+      trackEvent('wallet_connected')
     } catch (error) {
       setError({
         fieldErrors: { walletAddress: [(error as Error).message] },

frontend/app/components/redesign/components/landing/ToolCard.tsx

@@ -2,6 +2,7 @@ import React, { useId } from 'react'
 import { Link } from 'react-router'
 import { PillTag } from '@/components'
 import arrowOutwardIcon from '~/assets/images/landing/arrow-outward.svg'
+import { useTrackEvent } from '~/lib/analytics'
 
 export type ToolCardProps = {
   children?: React.ReactNode
@@ -22,12 +23,17 @@ export const ToolCard = ({
   target,
   className = '',
 }: ToolCardProps) => {
+  const trackEvent = useTrackEvent()
   const id = useId()
   const linkContent = title
   const linkClasses =
     'font-bold text-xl leading-normal text-text-primary after:absolute after:inset-0 after:z-10'
   const isExternalLink = target !== undefined
 
+  const handleClick = () => {
+    trackEvent('click_card_tool', { link: to })
+  }
+
   return (
     <article
       className={`bg-interface-bg-main rounded-2xl w-full max-w-[330px] p-md pb-xl flex flex-col gap-md relative group hover:bg-white hover:cursor-pointer focus-within:bg-white ${className}`}
@@ -44,11 +50,12 @@ export const ToolCard = ({
               target={target}
               rel={target === '_blank' ? 'noreferrer' : undefined}
               className={linkClasses}
+              onClick={handleClick}
             >
               {linkContent}
             </a>
           ) : (
-            <Link to={to} className={linkClasses}>
+            <Link to={to} className={linkClasses} onClick={handleClick}>
               {linkContent}
             </Link>
           )}

frontend/app/lib/analytics.tsx

@@ -0,0 +1,28 @@
+import { createContext, useCallback, useContext } from 'react'
+import type { ReactNode } from 'react'
+import { useLocation } from 'react-router'
+import { TOOLS } from '@shared/types'
+
+type TrackFn = (
+  eventName: string,
+  eventData?: Record<string, string | number | boolean | null>,
+) => void
+
+const TrackContext = createContext<TrackFn>(() => {})
+
+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)
+    },
+    [tool],
+  )
+  return <TrackContext.Provider value={track}>{children}</TrackContext.Provider>
+}
+
+export function useTrackEvent(): TrackFn {
+  return useContext(TrackContext)
+}

frontend/app/lib/types.ts

@@ -63,6 +63,12 @@ export type ElementErrors = {
 }
 
 declare global {
+  interface Window {
+    umami?: {
+      track(eventName: string, eventData?: Record<string, unknown>): void
+    }
+  }
+
   interface Env {
     OP_KEY_ID: string
     OP_PRIVATE_KEY: string

frontend/app/root.tsx

@@ -11,26 +11,44 @@ import {
   type MetaFunction,
 } from 'react-router'
 import { Header, Footer } from '@/components'
+import { APP_URL, UMAMI_HOST, UMAMI_WEBSITE_ID } from '@shared/defines'
 import faviconSvg from '~/assets/images/favicon.svg?url'
+import { TelemetryProvider } from '~/lib/analytics'
 import { UIProvider } from '~/stores/uiStore'
 import stylesheet from '~/tailwind.css?url'
 import { XCircle } from './components/icons.js'
 import { Button } from './components/index.js'
 
 export default function App() {
+  const domain = new URL(
+    process.env.NODE_ENV === 'development'
+      ? APP_URL.development
+      : APP_URL.production,
+  ).hostname
+
   return (
     <html lang="en">
       <head>
         <meta charSet="utf-8" />
         <meta name="viewport" content="width=device-width, initial-scale=1" />
         <Meta />
         <Links />
+        {UMAMI_HOST && UMAMI_WEBSITE_ID && (
+          <script
+            defer
+            src={`${UMAMI_HOST}/script.js`}
+            data-website-id={UMAMI_WEBSITE_ID}
+            data-domains={domain}
+          />
+        )}
       </head>
       <body className="h-screen bg-interface-bg-main flex flex-col">
         <UIProvider>
           <Header />
           <main className="flex-grow flex flex-col">
-            <Outlet />
+            <TelemetryProvider>
+              <Outlet />
+            </TelemetryProvider>
           </main>
           <Footer />
         </UIProvider>