Add Analytics

Hook up analytics using PostHog.

Use PostHog to track page views and user interactions, as well as to show a visitor hit counter in your production build.

PostHog Setup

Retrieve PostHog Variables

From the PostHog dashboard's left sidebar, click Settings:

Under Settings - General:

Copy your Project token. Enter this into your .env.local file under your NEXT_PUBLIC_POSTHOG_KEY:
```
NEXT_PUBLIC_POSTHOG_KEY=<your-project-token>
```
Under SDK setup, grab the api_host value from one of the snippets (For example, https://us.i.posthog.com). Enter this into your .env.local file under your NEXT_PUBLIC_POSTHOG_HOST:
```
NEXT_PUBLIC_POSTHOG_HOST=<your-project-api-host>
```
Copy your Project ID. Enter this into your .env.local file under your POSTHOG_PROJECT_ID:
```
POSTHOG_PROJECT_ID=<your-project-id>
```

In the Settings left sidebar, select Personal API keys under Account.
Click + Create personal API key.
Give the key a Label. For example: Guestbook Hit Counter
Under Organizations & project access, select Projects then the project you want to grant access to.
Under Scopes, select Query: Read.
Click Create key.
1. Copy your API key after it generates. Enter this into your .env.local file under your POSTHOG_PERSONAL_API_KEY:
```
POSTHOG_PERSONAL_API_KEY=<your-personal-api-key>
```
2. For your POSTHOG_API_HOST, enter the app host for the Query API (For example: https://us.posthog.com, not the *.i.posthog.com ingest host):
```
POSTHOG_API_HOST=<your-api-host>
```

Configure PostHog

For cloud deployment:

If you are deploying to Vercel:

In the left sidebar of your guestbook project, select Environment Variables.
Click Add Environment Variable.

Enter the following as Config Type variables:

NEXT_PUBLIC_POSTHOG_KEY=<your-project-token>
NEXT_PUBLIC_POSTHOG_HOST=<your-project-api-host>
FLAG_COUNTER=true
# End `FLAG_COUNTER_URL` with a trailing slash for one exact page
FLAG_COUNTER_URL=https://<your-project-url>.vercel.app/
# Use PostHog UTC time: `YYYY-MM-DD HH:mm:ss` (or `YYYY-MM-DD` for midnight)
# Leave `FLAG_COUNTER_DATE` empty to count all time
FLAG_COUNTER_DATE=2026-09-16 00:00:00

Enter the following as Secret Type variables:

# IMPORTANT: MAKE SURE THEY ARE SECRET SO THEY ARE HIDDEN
POSTHOG_PERSONAL_API_KEY=<your-personal-api-key>
POSTHOG_PROJECT_ID=<your-project-id>
POSTHOG_API_HOST=<your-api-host>

From the PostHog dashboard's left sidebar, click Settings.
Under Products, select Web analytics.
Under Web analytics domains, click + Add new authorized URL.
Enter in the URL of your deployed guestbook application, including the trailing slash if you want to gate only to your guestbook page. For example: https://<your-project-url>.vercel.app/
Click Save.

Enabling Hit Counter

Enable Hit Counter

In your next.config.ts (or next.config.js), insert FLAG_COUNTER under env:

const nextConfig: NextConfig = {
  env: {
    FLAG_COUNTER: process.env.FLAG_COUNTER,
  },
  // your existing options
};

In .env.local (for local development) or your Vercel environment variables (for cloud deployment):

Set FLAG_COUNTER= to true.

Scope the counter with FLAG_COUNTER_URL=.

An empty FLAG_COUNTER_URL counts every $pageview in your PostHog project.
Each entered URL scopes to one exact page ($host + $pathname) — subpages are not included.
Always use a trailing slash on full URLs.

# Home board (this page only)
FLAG_COUNTER_URL=https://<your-project-url>.vercel.app/

# Nested board (this page only, not /guestbook/admin)
FLAG_COUNTER_URL=https://<your-site>.vercel.app/guestbook/

# Path only — same exact-page match; on Vercel this is also scoped to the production host
FLAG_COUNTER_URL=/

# Several exact pages
FLAG_COUNTER_URL=https://example.com/,https://example.com/guestbook/

Optionally set FLAG_COUNTER_DATE= so unique $pageview visitors are counted only at or after that UTC time. Use the same timestamp format as PostHog SQL (toDateTime).
```
# Exact UTC instant (same string as in HogQL)
FLAG_COUNTER_DATE=2026-09-18 01:57:00

# Midnight UTC on that calendar day
FLAG_COUNTER_DATE=2026-09-16
```
Leave it empty to count all time. Values that do not match those formats are ignored.

Enable Live Counter

Create app/api/hits/route.ts which polls /api/hits in production:

export { GET } from "y2k-guestbook/hits";
export const dynamic = "force-dynamic";

Enable Web Tracking

Install posthog-js to enable capture of client pageviews, clicks, and session replay:
```
npm install posthog-js
```
Copy instrumentation-client.ts.example as src/instrumentation-client.ts (or the project root if there is no src/):
```
npx y2k-guestbook init-instrumentation
```
Next.js only loads the exact filename instrumentation-client.ts. Do not paste the PostHog HTML snippet into your layout.
The example initializes PostHog only when NODE_ENV === "production", with person_profiles: "always" which captures pageviews, clicks, and session replay via the SDK defaults.
From the PostHog dashboard's left sidebar, click Settings.
Under Products, select Session replay. Toggle ON:
- Record user sessions
- Log capture
- Canvas capture

Test Hit Counter & Tracking

Development builds do not send $pageview events. To grow the count, build and serve (or use a Vercel deployment) so instrumentation-client.ts can capture:

# Linter check for errors
npm run lint
# Compile
npm run build
# Serve build 
npm run start

Confirm the hit counter matches an exact-page query (not a $current_url LIKE, which includes subpages):

From the PostHog dashboard's left sidebar, click Product analytics.
Click + New, then select SQL.

Enter a SQL query that matches FLAG_COUNTER_URL and FLAG_COUNTER_DATE:

-- Home: FLAG_COUNTER_URL=https://<your-project-url>.vercel.app/
-- FLAG_COUNTER_DATE=2026-09-18 01:57:00
SELECT uniq(distinct_id)
FROM events
WHERE event = '$pageview'
AND properties.$host = '<your-project-url>.vercel.app'
AND properties.$pathname = '/'
AND timestamp >= toDateTime('2026-09-18 01:57:00', 'UTC')

-- Nested board: FLAG_COUNTER_URL=https://example.com/guestbook/
SELECT uniq(distinct_id)
FROM events
WHERE event = '$pageview'
AND properties.$host = 'example.com'
AND properties.$pathname = '/guestbook'
AND timestamp >= toDateTime('2026-09-18 01:57:00', 'UTC')

-- Several exact pages
SELECT uniq(distinct_id)
FROM events
WHERE event = '$pageview'
AND (
    (properties.$host = 'example.com' AND properties.$pathname = '/')
    OR (properties.$host = 'example.com' AND properties.$pathname = '/guestbook')
)
AND timestamp >= toDateTime('2026-09-18 01:57:00', 'UTC')

Add Analytics

PostHog Setup

Retrieve PostHog Variables

Configure PostHog

Enabling Hit Counter

Enable Hit Counter

Enable Live Counter

Enable Web Tracking

Test Hit Counter & Tracking

What's Next