Skip to content

Full Toolkit for Next-Level Domain Analysis

Measure how many visitors BotID flags as bots 🤖🧪 (#155)

Felix Wotschofskydd882d88c207
diff --git a/app/api/is-human/route.test.ts b/app/api/is-human/route.test.ts
new file mode 100644
index 0000000..3010a16
--- /dev/null
+++ b/app/api/is-human/route.test.ts
@@ -0,0 +1,24 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { POST } from './route';
+
+const { checkBotId } = vi.hoisted(() => ({ checkBotId: vi.fn() }));
+vi.mock('botid/server', () => ({ checkBotId }));
+vi.mock('@/lib/evlog', () => ({
+ useLogger: () => ({ set: vi.fn() }),
+ withEvlog: (handler: unknown) => handler,
+}));
+
+describe('is-human API', () => {
+ it.each([
+ ['a human', { isHuman: true, bypassed: false }, true],
+ ['a bot', { isHuman: false, bypassed: false }, false],
+ ['a bypassed check', { isHuman: true, bypassed: true }, false],
+ ])('answers %s with isHuman %s', async (_, verdict, isHuman) => {
+ checkBotId.mockResolvedValue(verdict);
+
+ const response = await POST();
+
+ expect(await response.json()).toEqual({ isHuman });
+ });
+});
diff --git a/app/api/is-human/route.ts b/app/api/is-human/route.ts
new file mode 100644
index 0000000..d93f0eb
--- /dev/null
+++ b/app/api/is-human/route.ts
@@ -0,0 +1,15 @@
+import { checkBotId } from 'botid/server';
+import { NextResponse } from 'next/server';
+
+import { useLogger, withEvlog } from '@/lib/evlog';
+
+// BotID's verdict for a visitor (app/providers.tsx). Firewall
+// bypass rules and local dev skip BotID but still report a human, so they're
+// reported as not human.
+export const POST = withEvlog(async () => {
+ const log = useLogger();
+ const { isHuman, bypassed } = await checkBotId();
+ log.set({ isHuman, bypassed });
+
+ return NextResponse.json({ isHuman: isHuman && !bypassed });
+});
diff --git a/app/providers.test.ts b/app/providers.test.ts
new file mode 100644
index 0000000..ad711a7
--- /dev/null
+++ b/app/providers.test.ts
@@ -0,0 +1,33 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { reportBotIdVerdict } from './providers';
+
+const respond = (body: string, status = 200) =>
+ vi.stubGlobal(
+ 'fetch',
+ vi.fn(async () => new Response(body, { status })),
+ );
+
+describe('BotID trial', () => {
+ afterEach(() => vi.unstubAllGlobals());
+
+ it.each([
+ ['a human verdict', '{"isHuman":true}', 200, 'human'],
+ ['a bot verdict', '{"isHuman":false}', 200, 'bot'],
+ // A failed check must not inflate the bot share the trial measures
+ ['a server error with a JSON body', '{"message":"failed"}', 500, 'error'],
+ ['a non-JSON response', '<html>challenge</html>', 403, 'error'],
+ ])('reports %s as %s', async (_, body, status, result) => {
+ respond(body, status);
+ const reportEvent = vi.fn();
+
+ await reportBotIdVerdict(reportEvent);
+
+ // Non-interactive, so the event doesn't turn bounces into engaged visits
+ expect(reportEvent).toHaveBeenCalledWith(
+ 'BotID: Check',
+ { result },
+ { interactive: false },
+ );
+ });
+});
diff --git a/app/providers.tsx b/app/providers.tsx
index 53fd2be..6c64fd9 100644
--- a/app/providers.tsx
+++ b/app/providers.tsx
@@ -3,10 +3,38 @@
import { EvlogProvider } from 'evlog/next/client';
import PlausibleProvider from 'next-plausible';
import { ThemeProvider } from 'next-themes';
-import { type ComponentProps, type FC, type ReactNode } from 'react';
+import { type ComponentProps, type FC, type ReactNode, useEffect } from 'react';
import { SWRConfig } from 'swr';
import { env } from '@/env';
+import { useAnalytics } from '@/lib/analytics';
+
+// Trial: reports BotID's verdict for every visitor as a Plausible event, so the
+// share of visitors it would drop from analytics can be measured before
+// analytics are gated on it.
+export const reportBotIdVerdict = (
+ reportEvent: ReturnType<typeof useAnalytics>['reportEvent'],
+) =>
+ fetch('/api/is-human', { method: 'POST' })
+ .then((response) => {
+ // A failed check is an error, never a bot verdict
+ if (!response.ok) throw new Error(`HTTP ${response.status}`);
+ return response.json();
+ })
+ .then((body): 'human' | 'bot' => (body.isHuman === true ? 'human' : 'bot'))
+ .catch(() => 'error' as const)
+ .then((result) =>
+ // Non-interactive, so single-page visits still count as bounces
+ reportEvent('BotID: Check', { result }, { interactive: false }),
+ );
+
+const useBotIdTrial = () => {
+ const { reportEvent } = useAnalytics();
+
+ useEffect(() => {
+ reportBotIdVerdict(reportEvent);
+ }, [reportEvent]);
+};
type CustomizedPlausibleProviderProps = {
children: ReactNode;
@@ -46,16 +74,20 @@ type ProvidersProps = {
children: ReactNode;
};
-export const Providers: FC<ProvidersProps> = ({ children }) => (
- <EvlogProvider
- service="domain-digger"
- // Using the non-default endpoint since default _evlog is considered hidden by Next.js
- transport={{ enabled: true, endpoint: '/api/evlog/ingest' }}
- >
- <ThemeProvider attribute="class">
- <SWRConfig value={{ fetcher: swrFetcher }}>
- <CustomizedPlausibleProvider>{children}</CustomizedPlausibleProvider>
- </SWRConfig>
- </ThemeProvider>
- </EvlogProvider>
-);
+export const Providers: FC<ProvidersProps> = ({ children }) => {
+ useBotIdTrial();
+
+ return (
+ <EvlogProvider
+ service="domain-digger"
+ // Using the non-default endpoint since default _evlog is considered hidden by Next.js
+ transport={{ enabled: true, endpoint: '/api/evlog/ingest' }}
+ >
+ <ThemeProvider attribute="class">
+ <SWRConfig value={{ fetcher: swrFetcher }}>
+ <CustomizedPlausibleProvider>{children}</CustomizedPlausibleProvider>
+ </SWRConfig>
+ </ThemeProvider>
+ </EvlogProvider>
+ );
+};
diff --git a/instrumentation-client.ts b/instrumentation-client.ts
new file mode 100644
index 0000000..4db93e1
--- /dev/null
+++ b/instrumentation-client.ts
@@ -0,0 +1,11 @@
+import { initBotId } from 'botid/client/core';
+
+initBotId({ protect: [{ path: '/api/is-human', method: 'POST' }] });
+
+// Queue Plausible events reported before its script loads (such as the BotID
+// check in app/providers.tsx); the script replays them once loaded.
+const queue: unknown[][] = [];
+(window as { plausible?: unknown }).plausible ??= Object.assign(
+ (...args: unknown[]) => queue.push(args),
+ { q: queue },
+);
diff --git a/lib/analytics.test.ts b/lib/analytics.test.ts
new file mode 100644
index 0000000..5c52898
--- /dev/null
+++ b/lib/analytics.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { useAnalytics } from './analytics';
+
+const { plausible } = vi.hoisted(() => ({ plausible: vi.fn() }));
+vi.mock('next-plausible', () => ({ usePlausible: () => plausible }));
+vi.mock('evlog/next/client', () => ({ log: { info: vi.fn() } }));
+vi.mock('react', () => ({ useCallback: (callback: unknown) => callback }));
+
+describe('reportEvent', () => {
+ it('passes interactive: false through to Plausible', () => {
+ useAnalytics().reportEvent(
+ 'BotID: Check',
+ { result: 'bot' },
+ { interactive: false },
+ );
+
+ expect(plausible).toHaveBeenCalledWith('BotID: Check', {
+ props: { result: 'bot' },
+ interactive: false,
+ });
+ });
+});
diff --git a/lib/analytics.ts b/lib/analytics.ts
index 70da3cc..cf35993 100644
--- a/lib/analytics.ts
+++ b/lib/analytics.ts
@@ -5,6 +5,7 @@ import { useCallback } from 'react';
type EmptyEvent = Record<string, never>;
type Events = {
+ 'BotID: Check': { result: 'human' | 'bot' | 'error' };
'Carbon Ad: Blocked': { reason: 'script' | 'no-ad' };
'Carbon Ad: Show': EmptyEvent;
'Copy Button: Click': { value: string };
@@ -26,9 +27,14 @@ export const useAnalytics = () => {
// Stable so it can sit in effect dependencies
const reportEvent = useCallback(
- <T extends keyof Events>(event: T, props: Events[T]) => {
+ <T extends keyof Events>(
+ event: T,
+ props: Events[T],
+ // interactive: false keeps an event from counting against bounce rate
+ options?: { interactive?: boolean },
+ ) => {
log.info({ message: 'analytics_event', event, props });
- plausible(event, { props });
+ plausible(event, { props, ...options });
},
[plausible],
);
diff --git a/package.json b/package.json
index a7831f2..553ea19 100644
--- a/package.json
+++ b/package.json
@@ -32,6 +32,7 @@
"@uidotdev/usehooks": "^2.4.1",
"@vercel/analytics": "^2.0.1",
"@vercel/speed-insights": "^2.0.0",
+ "botid": "^1.5.12",
"class-variance-authority": "^0.7.1",
"clsx": "^2.1.1",
"dataloader": "^2.2.3",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 43ea61e..104efea 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -60,6 +60,9 @@ importers:
'@vercel/speed-insights':
specifier: ^2.0.0
+ botid:
+ specifier: ^1.5.12
class-variance-authority:
specifier: ^0.7.1
version: 0.7.1
@@ -2532,6 +2535,17 @@ packages:
resolution: {integrity: sha512-JZOSA7Mo9sNGB8+UjSgzdLtokWAky1zbztM3WRLCbZ70/3cTANmQmOdR7y2g+J0e2WXywy1yS468tY+IruqEww==}
+ resolution: {integrity: sha512-bUYGLDLbNOQJyTVfuBGzm1ADztJ/euV6XH9JgXZ9MG2CZvElgOycybVOsgHBjVwB4tFl77g7zs31kEvjYm2gAw==}
+ peerDependencies:
+ next: '*'
+ react: ^18.0.0 || ^19.0.0
+ peerDependenciesMeta:
+ next:
+ optional: true
+ react:
+ optional: true
+
resolution: {integrity: sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==}
@@ -6829,6 +6843,11 @@ snapshots:
+ optionalDependencies:
+ react: 19.3.1
+
dependencies:
balanced-match: 1.0.2