Admin Analytics

Admin analytics measures how teams use the Flaggr console itself. It complements browser analytics: browser analytics measures your application experience, while admin analytics measures the flag workflow from discovery to activation.

Use it to answer operational questions:

• Are users finding the flags they need?
• How many users move from flag detail views to toggles or targeting rules?
• How long does it take an experiment to move from start to decision?
• Do teams return to newly created flags after setup?

Where to Find It

Open a project and navigate to Console > [Project] > Analytics. The Overview tab's More analytics panel links to:

Both pages require project read access and use the same project isolation rules as the rest of the console.

What Gets Collected

The console records first-party admin events from the web app. Events are batched in the browser and posted to /ingest/admin-events with your console session. The server sets each event's project ID and slug, and drops events for projects you can't read, so no one can write into another project's admin funnel.

Event properties are limited to primitive values such as strings, numbers, and booleans. Project identifiers, project slugs, flag keys, route names, app version, build number, and platform are included where available so analytics can be filtered by project and release. Before storage the server scrubs them: the route property (the console's path and query) loses its fragment and has credential-like query values redacted, including those inside a nested next= URL, and a user ID that holds an email address or a JWT is stored as null.

Admin Funnel

The admin funnel turns console events into three workflow steps:

Each step reports:

• users: actors who reached the step
• conversionRate: share of entry users who reached the step
• dropOffRate: share that dropped from the previous step

The page also shows a cycle proxy based on the median time between experiment_started and experiment_decision events.

Adoption Cohorts

Adoption cohorts group activity by week. A cohort is considered adopted when a project creates a flag and then records a matching flag_viewed event for that flag in the same weekly bucket.

Each row reports:

• createdProjects: project-week cohorts with created flags
• adoptedProjects: project-week cohorts that returned to view created flags
• adoptionRate: adopted cohorts divided by created cohorts

Use this page to check whether new flag setup leads to follow-up work instead of abandoned configuration.

Generate Local Test Data

Use the seed utility when you want realistic data for local bug bashing or UI validation:

npm run seed:consumer-analytics -- \
  --project-id proj_abc123 \
  --project-slug acme \
  --base-url http://127.0.0.1:3000 \
  --users 32

The command posts synthetic admin events to /ingest/admin-events and prints direct links to the admin funnel and adoption cohort pages. The ingest takes only a signed-in console session, so the command sends one as Authorization: Bearer on every post and on the --verify reads: a Firebase ID token from --id-token <token> or FLAGGR_ID_TOKEN. The console's own requests carry one in their Authorization header, and it expires after an hour. API tokens, SDK keys and personal access tokens are refused.

Against localhost, 127.0.0.1 or [::1] the command defaults to the local development token: NEXT_PUBLIC_LOCAL_DEV_TOKEN as next dev reads it (from the shell, else from .env.development.local, .env.local, .env.development or .env), else the built-in one. Only a development server accepts that token, so it works against npm run dev, including the Playwright e2e server. A local server that runs next start with BYPASS_AUTH_FOR_TESTS=true (the integration-test server) refuses it with 403 ADMIN_EVENTS_SESSION_ONLY. There, add --no-auth (or set FLAGGR_ID_TOKEN=none) to send no Authorization header, and every request is the test user.

The session must be able to read --project-id. The ingest answers 202 first, with accepted counting the events queued, and then drops the events of a project the session can't read. Add --verify to read the admin funnel and cohort APIs back afterwards; --users (default 24), --site-id (default NEXT_PUBLIC_FLAGGR_ANALYTICS_SITE_ID, else flaggr_admin_preview) and --span-minutes (default 90, at most 110) are also available.

Against a deployment, pass a Firebase ID token for an account that can read the project:

FLAGGR_ID_TOKEN=<Firebase ID token> npm run seed:consumer-analytics -- \
  --project-id proj_abc123 \
  --project-slug acme \
  --base-url https://preview.flaggr.dev \
  --verify

To inspect the generated payload without writing data (no token needed):

npm run seed:consumer-analytics -- \
  --project-id proj_abc123 \
  --project-slug acme \
  --print

Query via API

Admin analytics endpoints are documented in the Analytics API Reference:

• GET /api/analytics/admin-funnel
• GET /api/analytics/adoption-cohorts
• POST /ingest/admin-events (console session only)

All query endpoints require authentication and project access. If Postgres analytics storage is not configured, the API returns 503 Analytics not configured.

Next Steps

• Analytics Dashboard - Understand how admin analytics fits into the full analytics dashboard
• Browser Analytics - Measure application Web Vitals, sessions, and flag impact
• Analytics API Reference - Query admin and browser analytics programmatically