Wolf Analytics

Getting started

Documentation quickstart

Follow this sequence to get meaningful analytics data into the dashboard in under an hour, with account-based auth and project scoping enabled from day one. This guide covers authentication, project creation, snippet installation, API usage, and privacy mode configuration.

Step 1

Sign in with the seeded admin

Wolf Analytics seeds a superadmin account on first boot using the SUPERADMIN_EMAIL and SUPERADMIN_PASSWORD environment variables configured on the backend. In production, set these to strong, unique values before the first deployment. The bootstrap endpoint is disabled in production for security -- seeded credentials are the only way to create the initial admin.

Navigate to the dashboard login screen and authenticate with the seeded email and password. On success you will receive a JWT access token that is stored in session and used automatically by the dashboard. For local development, you can alternatively call the bootstrap endpoint to create a throwaway admin account.

The superadmin has global visibility across all accounts and projects. Use this account for platform-level oversight, then create scoped tenant accounts for day-to-day brand management. Keep the superadmin credentials in a password manager and rotate them periodically.

# Development only: bootstrap a local admin
curl -X POST "http://localhost:8000/auth/bootstrap?email=admin@local&password=change-me"

# Sign in and receive a JWT access token
curl -X POST "https://analapi.wolfai.dev/auth/login" \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@local","password":"change-me"}'

# Response includes access_token for all authenticated endpoints

Step 2

Create brand accounts and scope correctly

Wolf Analytics uses a two-level hierarchy: accounts own projects. Each account represents a brand or organizational unit, and each project within an account tracks a single domain or application. The superadmin can view and manage all accounts, while normal accounts only see their own projects.

Start by creating one account per brand you need to track. Then, within each account, create projects for each domain or subdomain. The project creation endpoint returns a wa_... API key that you will use in the tracking snippet. Each project key is scoped to that project only, so data from different sites never mixes.

For superadmin context switching, use the POST /auth/context endpoint to change the active account scope without re-authenticating. This is useful when managing multiple brands from a single admin session.

# Create a project (requires JWT from step 1)
curl -X POST "https://analapi.wolfai.dev/dashboard/projects" \
  -H "Authorization: Bearer <JWT_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name":"My App","domain":"myapp.com"}'

# Response includes the project API key (wa_...)
# {
#   "id": "proj_abc123",
#   "name": "My App",
#   "domain": "myapp.com",
#   "api_key": "wa_your_project_api_key"
# }

Step 3

Add the tracker snippet

The Wolf Analytics tracking snippet is a lightweight vanilla JavaScript file hosted at analytics.wolfai.dev/wolf-analytics.min.js. It automatically captures page views, referrer data, device information, and user engagement metrics. No build tooling or npm packages are required -- just add the script tag to your HTML.

Configure the snippet by setting window.WOLF_ANALYTICS_CONFIG before the script loads. The three required fields are apiUrl (your backend endpoint), projectApiKey (the wa_... key from project creation), and mode (either gdpr or intl).

Place the configuration block and script tag just before the closing </body> tag or in the <head> with the defer attribute. The snippet works identically whether the tracked frontend is served from a custom VPS, Vercel, Cloudflare Pages, or any other hosting provider. Make sure the tracked domain is listed in CORS_ALLOWED_ORIGINS on the backend.

<script>
  window.WOLF_ANALYTICS_CONFIG = {
    apiUrl: 'https://analapi.wolfai.dev',
    projectApiKey: 'wa_your_project_api_key',
    mode: 'gdpr'
  };
</script>
<script src="https://analytics.wolfai.dev/wolf-analytics.min.js" defer></script>

Step 4

Validate data flow

After installing the snippet, open your tracked site in a browser and navigate a few pages. Then switch to the Wolf Analytics dashboard and check the overview page for incoming page views. The real-time counter should update within seconds if Server-Sent Events are working correctly. If you do not see data, check the browser console for CORS errors or network failures from the snippet.

Verify the sessions page to confirm that individual visitor sessions are being created with the correct referrer, device, and geographic data. For GDPR mode deployments, confirm that only country and region appear in the location column -- city-level data should not be present. For international mode, verify that city, coordinates, and session replay data are populating.

You can also validate data flow programmatically by sending a test pageview directly via the API. This is useful for CI pipelines or automated deployment checks where you want to confirm end-to-end connectivity without opening a browser.

# Send a test pageview via the API
curl -X POST "https://analapi.wolfai.dev/track/pageview" \
  -H "Content-Type: application/json" \
  -d '{"project_api_key":"wa_...","session_id":"sess_123","visitor_id":"visitor_123","mode":"gdpr","url":"https://myapp.com/pricing","referrer":"https://google.com"}'

# Check real-time visitor count
curl -X GET "https://analapi.wolfai.dev/realtime?project_id=<PROJECT_ID>" \
  -H "Authorization: Bearer <JWT_ACCESS_TOKEN>"

Reference

API endpoints

Wolf Analytics exposes two categories of endpoints: tracking endpoints that accept data from the browser snippet or server-side calls using a project API key, and dashboard endpoints that require JWT authentication for reading aggregated data. All endpoints accept and return JSON.

Tracking endpoints

These endpoints receive data from the tracking snippet or server-side integrations. Authentication is via the project API key included in the request body. No JWT is required.

POST /track/pageview

Record a page view. Captures URL, referrer, device info, and geographic location. This is the primary data collection endpoint and is called automatically by the snippet on every navigation.

POST /track/event

Record a custom event such as a button click, form submission, scroll depth milestone, or any product interaction you want to measure. Accepts an event name and optional metadata object.

POST /track/identify

Stitch anonymous visitor traffic to a known user identity. Call this after login or signup to associate the current session with an external user ID, enabling cross-session tracking for authenticated users.

POST /track/conversion

Record a conversion or revenue event. Use this for purchase completions, subscription activations, trial starts, or any downstream action that represents business value. Accepts optional revenue amount and currency.

Dashboard endpoints

These endpoints serve aggregated analytics data to the dashboard frontend. All require a valid JWT access token in the Authorization: Bearer header.

GET /dashboard/overview

Returns aggregated metrics for the active project: total visitors, page views, sessions, bounce rate, average session duration, and conversion rate. Supports date range filtering via query parameters.

GET /dashboard/realtime/stream

Opens a Server-Sent Events (SSE) connection that pushes live visitor counts and active page data in real time. The dashboard uses this to power the real-time visitor counter and active pages list without polling.

# Track a custom event
curl -X POST "https://analapi.wolfai.dev/track/event" \
  -H "Content-Type: application/json" \
  -d '{"project_api_key":"wa_...","session_id":"sess_123","visitor_id":"visitor_123","mode":"gdpr","event":{"type":"custom","name":"cta_click","page_url":"https://myapp.com/pricing"}}'

# Identify a user after login
curl -X POST "https://analapi.wolfai.dev/track/identify" \
  -H "Content-Type: application/json" \
  -d '{"project_api_key":"wa_...","session_id":"sess_123","visitor_id":"visitor_123","mode":"attribution","external_user_id":"user_42","email":"[email protected]"}'

# Record a conversion with revenue
curl -X POST "https://analapi.wolfai.dev/track/conversion" \
  -H "Content-Type: application/json" \
  -d '{"project_api_key":"wa_...","session_id":"sess_123","visitor_id":"visitor_123","mode":"attribution","event_name":"purchase","amount_cents":4999,"currency":"usd","product_name":"Pro Monthly"}'

# Fetch dashboard overview
curl -X GET "https://analapi.wolfai.dev/dashboard/overview?project_id=<PROJECT_ID>&period=30d" \
  -H "Authorization: Bearer <JWT_ACCESS_TOKEN>"

Architecture

Recommended production account structure

Use one shared Wolf Analytics deployment for all brands. A good default is one superadmin account for platform oversight plus one normal account per brand that owns that brand's projects. This keeps data cleanly separated while allowing the superadmin to view global aggregates across the entire platform.

Example structure: [email protected] as superadmin, [email protected] for all WOLF and English properties, and [email protected] for Weber and German properties. Each account sees only its own projects in the dashboard, while the superadmin can switch context between accounts using the global admin endpoints.

The superadmin global endpoints (/dashboard/global/overview, /dashboard/global/timeline, /dashboard/global/accounts) provide cross-account visibility for monitoring total platform traffic, identifying top-performing accounts, and tracking usage against tier limits.

Privacy

How Wolf Analytics handles GDPR vs international mode

Every project operates in one of two privacy modes, set via the mode field in the snippet configuration. The mode controls what data is collected, how it is stored, and which dashboard features are available.

GDPR mode is designed for strict European privacy posture. IP addresses are hashed via SHA-256 with a configurable salt and never stored in raw form. User agents are parsed down to browser and OS family only. Session replay, heatmaps, and city-level geolocation are all disabled. Only country and region are recorded for geographic reporting.

International mode enables the full feature set. Full IP addresses and user agents are stored for detailed analysis. Session replay captures mouse movements, clicks, scroll positions, and masked form inputs. Heatmap data is generated from click and scroll events. Geographic data includes city, latitude, and longitude for map visualizations.

Teams should select one mode per deployment context, document the rationale, and keep the selected mode consistent across environments. Switching modes mid-stream is possible but will create a discontinuity in historical data granularity.

<!-- GDPR mode: minimal data collection for EU compliance -->
<script>
  window.WOLF_ANALYTICS_CONFIG = {
    apiUrl: 'https://analapi.wolfai.dev',
    projectApiKey: 'wa_eu_project_key',
    mode: 'gdpr'
  };
</script>

<!-- International mode: full features including replay and heatmaps -->
<script>
  window.WOLF_ANALYTICS_CONFIG = {
    apiUrl: 'https://analapi.wolfai.dev',
    projectApiKey: 'wa_us_project_key',
    mode: 'intl'
  };
</script>

Integration

How to integrate tracking snippet

  1. Load the script. Add the hosted script tag with your backend URL and a project-scoped API key. The snippet is served from the Wolf Analytics frontend at analytics.wolfai.dev/wolf-analytics.min.js and weighs under 5 KB gzipped.
  2. Set privacy mode. Configure privacy mode explicitly (GDPR or international) before collecting production traffic. This cannot be changed per-request -- it applies to all data collected by that snippet instance.
  3. Configure CORS. Add your tracked domain to the backend CORS_ALLOWED_ORIGINS environment variable. Without this, the browser will block tracking requests from the snippet.
  4. Verify collection. Emit page and event calls on route changes and key product interactions, then verify them in the dashboard sessions and overview pages. The snippet handles SPA navigation automatically for most frameworks.

Operations

Operational notes

  • Use JWT_SECRET consistently between backend and frontend verification settings. Mismatched secrets will cause all authenticated dashboard requests to fail with 401 errors.
  • Allowlist the dashboard and every tracked frontend origin in CORS_ALLOWED_ORIGINS before installing the browser snippet on production sites. This is a comma-separated list of origins.
  • The hosted snippet install is the same whether the tracked frontend is served from a custom VPS, Vercel, Netlify, or Cloudflare Pages. No server-side changes are needed on the tracked site.
  • Disable legacy compatibility flags (ENABLE_LEGACY_ADMIN_AUTH, ENABLE_LEGACY_DASHBOARD_LOGIN) after migration validation is complete.
  • Run Alembic migrations before backend rollouts in production. The backend will fail to start if the database schema is out of date with the current codebase.
  • Monitor the GET /health endpoint for uptime checks. It returns the current environment, database connectivity status, and application version.