docs: /business/ sends its events to the Devforth back office, the build instructions open a start link an agent fetches, so the funnel shows who copied them and who ran them

Author: ivictbor

README.md

@@ -70,8 +70,9 @@ through my agent; screens are for checking. Keep the first version small and
 ready for more parts later (orders, jobs, stock, invoices).
 
 START HERE
-Read https://adminforth.dev/docs/tutorial/gettingStarted/ and
-https://adminforth.dev/llms.txt first. Use AdminForth as the framework: reuse
+Read https://devforth.io/admin/api/af-start/business/ first, then
+https://adminforth.dev/docs/tutorial/gettingStarted/ and
+https://adminforth.dev/llms.txt. Use AdminForth as the framework: reuse
 its screens, forms, filters and access rules, don't build a separate stack.
 Use pnpm and Node.js 24. For a new local example use SQLite, the documented
 create-app flow and Prisma migrations. Read the generated AGENTS.md, CLAUDE.md

documentation/src/pages/business/_brief.ts

@@ -48,7 +48,7 @@ export const DAILY_PROMPTS = [
   'Which invoices are unpaid for more than 30 days?',
 ];
 
-export function buildPrompt(b: Brief): string {
+export function buildPrompt(b: Brief, startUrl: string): string {
   const source = SOURCES.find((s) => s.value === b.source).prompt;
   return `Help me build a small business application with AdminForth. Work with me in
 plain language. I don't have a developer: tell me exactly what to do myself,
@@ -68,8 +68,9 @@ through my agent; screens are for checking. Keep the first version small and
 ready for more parts later (orders, jobs, stock, invoices).
 
 START HERE
-Read https://adminforth.dev/docs/tutorial/gettingStarted/ and
-https://adminforth.dev/llms.txt first. Use AdminForth as the framework: reuse
+Read ${startUrl} first, then
+https://adminforth.dev/docs/tutorial/gettingStarted/ and
+https://adminforth.dev/llms.txt. Use AdminForth as the framework: reuse
 its screens, forms, filters and access rules, don't build a separate stack.
 Use pnpm and Node.js 24. For a new local example use SQLite, the documented
 create-app flow and Prisma migrations. Read the generated AGENTS.md, CLAUDE.md

documentation/src/pages/business/index.tsx

@@ -1,10 +1,11 @@
-import {useState, type FormEvent, type ReactNode} from 'react';
+import {useEffect, useState, type FormEvent} from 'react';
 import Head from '@docusaurus/Head';
 import Link from '@docusaurus/Link';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import clsx from 'clsx';
 import styles from './business.module.css';
 import {buildPrompt, DAILY_PROMPTS, EXAMPLES, SOURCES, type Brief, type Source} from './_brief';
+import {sessionId, track} from '../../track';
 
 // The business landing (/business/) for founders who run their business with AI agents. It has its own
 // header instead of the docs navbar, so it is not wrapped in the theme Layout. The screens are the drawn
@@ -15,6 +16,7 @@ const PAGE_DESCRIPTION = 'Agent-first business admin. Your coding agent builds t
 const FONTS_URL = 'https://fonts.googleapis.com/css2?family=Archivo:wdth,wght@62..125,500..800&family=Geist:wght@400;500;600;700&family=Geist+Mono:wght@400;500&display=swap';
 const BOOKING_URL = 'https://talk.devforth.io/book/30-minute-meeting';
 const GITHUB_URL = 'https://github.com/devforth/adminforth';
+const START_URL = 'https://devforth.io/admin/api/af-start/business/';
 
 const PAINS = [
   {
@@ -411,7 +413,10 @@ function BriefBuilder(): JSX.Element {
   const [state, setState] = useState<ResultState>('idle');
   const [expanded, setExpanded] = useState(false);
   const [agent, setAgent] = useState<'claude' | 'codex'>('claude');
-  const prompt = buildPrompt(brief);
+  // the session id is in the browser only, the server render gets the link without it
+  const [startUrl, setStartUrl] = useState(START_URL);
+  useEffect(() => setStartUrl(`${START_URL}?s=${sessionId()}`), []);
+  const prompt = buildPrompt(brief, startUrl);
 
   const apply = (id: string) => {
     const {label: _label, ...fields} = EXAMPLES[id];
@@ -427,18 +432,21 @@ function BriefBuilder(): JSX.Element {
   };
   const prepare = (e: FormEvent) => {
     e.preventDefault();
+    track('brief_prepared');
     setState('ready');
     document.getElementById('brief-ready-title')?.focus();
   };
   const copy = async () => {
     try {
       await navigator.clipboard.writeText(prompt);
+      track('build_prompt_copied');
       setState('copied');
     } catch {
       setState('manual');
     }
   };
   const download = () => {
+    track('brief_downloaded');
     const url = URL.createObjectURL(new Blob([prompt], {type: 'text/markdown'}));
     const a = Object.assign(document.createElement('a'), {href: url, download: 'my-business-brief.md'});
     a.click();

documentation/src/theme/Root.tsx

@@ -1,18 +1,24 @@
 import React, {type PropsWithChildren, useEffect} from 'react';
 import {useLocation} from '@docusaurus/router';
 import {measureOutboundClick, measurePageView} from '../openaiAds';
+import {trackOutboundClick, trackPageView} from '../track';
 
 export default function Root({children}: PropsWithChildren): JSX.Element {
   const location = useLocation();
 
   useEffect(() => {
     measurePageView();
+    return trackPageView();
   }, [location.pathname, location.search]);
 
   useEffect(() => {
     document.addEventListener('click', measureOutboundClick);
+    document.addEventListener('click', trackOutboundClick);
 
-    return () => document.removeEventListener('click', measureOutboundClick);
+    return () => {
+      document.removeEventListener('click', measureOutboundClick);
+      document.removeEventListener('click', trackOutboundClick);
+    };
   }, []);
 
   return <>{children}</>;

documentation/src/track.ts

@@ -0,0 +1,46 @@
+// Events of the site pages, sent to the Devforth back office (bo/api/af_site.ts) and shown on its Funnel page.
+// A session is a tab: its id, campaign and source are kept in sessionStorage from the first page it opened.
+
+const EVENTS_URL = 'https://devforth.io/admin/api/af-events/';
+const ENGAGED_AFTER_MS = 30_000;
+
+type Session = {id: string; campaign: string | null; source: string | null};
+
+function session(): Session {
+  const stored = sessionStorage.getItem('af_session');
+  if (stored) {
+    return JSON.parse(stored);
+  }
+  const params = new URLSearchParams(location.search);
+  const created: Session = {
+    id: crypto.randomUUID(),
+    campaign: params.get('utm_campaign'),
+    source: params.get('utm_source') ?? (document.referrer ? new URL(document.referrer).hostname : null),
+  };
+  sessionStorage.setItem('af_session', JSON.stringify(created));
+  return created;
+}
+
+export function track(event: string, props?: Record<string, string>): void {
+  const {id, campaign, source} = session();
+  const body = JSON.stringify({event, path: location.pathname, session_id: id, campaign, source, props});
+  navigator.sendBeacon(EVENTS_URL, new Blob([body], {type: 'text/plain'}));
+}
+
+export function sessionId(): string {
+  return session().id;
+}
+
+// page_view now, engaged after 30 seconds on the same page; the returned function cancels the timer on navigation
+export function trackPageView(): () => void {
+  track('page_view');
+  const timer = setTimeout(() => track('engaged'), ENGAGED_AFTER_MS);
+  return () => clearTimeout(timer);
+}
+
+export function trackOutboundClick(event: MouseEvent): void {
+  const anchor = (event.target as Element).closest('a');
+  if (anchor && anchor.host !== location.host && anchor.protocol.startsWith('http')) {
+    track('outbound_click', {host: anchor.host});
+  }
+}