Analytics
@ivangdavila
npx machina-cli add skill @ivangdavila/analytics --openclawCritical Implementation Gotchas
Umami API timestamps: Use milliseconds, not seconds. Date.now() in JS, int(time.time() * 1000) in Python.
Plausible API v2: Requires site_id parameter, NOT domain name. Get site_id from dashboard URL first.
PostHog events: Properties must be JSON serializable. Never pass DOM elements or functions.
Rate limits: Umami 600/hour, Plausible 600/hour, PostHog 1000/minute. Implement exponential backoff on 429.
Environment-Specific Setup
Development: ALWAYS use separate project/site for local testing. Production data pollution is irreversible.
Tracking domains: Never hardcode. Use env vars to switch between localhost and production.
Bot filtering: Enable in settings. Privacy tools have weaker bot detection than Google Analytics.
GDPR Compliance Gotchas
EU visitors need explicit consent even for privacy-first tools. Check IP geolocation before tracking.
Data retention: Set automatic deletion - Umami in Settings > Data, Plausible 30 days max, PostHog in project settings.
Cookie-free warning: Umami/Plausible don't use cookies but still need consent for EU visitors if collecting identifiers.
Runtime Safety
Verify script loads before sending events. Check for umami, plausible, or posthog globals first.
Never track PII (email, names, IP) in custom events. Violates privacy principles.
Batch PostHog events via /batch endpoint. Umami/Plausible require individual requests.
Authentication Patterns
Store API keys in environment variables only. Never hardcode.
Umami: Requires website ID + API key combination.
Plausible: Uses Bearer token authentication.
PostHog: Uses project-specific API key.
Overview
Deploy privacy-first analytics using Umami, Plausible, and PostHog with correct API patterns, rate limits, and GDPR controls. This skill guides API usage, environment setup, and consent-driven data handling to protect user privacy while delivering insights.
How This Skill Works
Events are emitted via tool-specific patterns: Umami with site_id + API key, Plausible with a Bearer token, and PostHog with a project API key. Use millisecond timestamps and JSON-serializable properties; never pass DOM elements or PII. Respect rate limits with exponential backoff and verify the analytics script loads before dispatching, using environment variables to switch tracking domains.
When to Use It
- Building a privacy-first analytics stack for a website or app.
- Migrating from cookies-based analytics to privacy-preserving tools.
- Setting up separate dev/prod projects to avoid production data pollution.
- Implementing GDPR-compliant tracking with explicit consent and geolocation gating.
- Configuring API-based events with correct authentication and rate-limiting.
Quick Start
- Step 1: Create separate dev/prod projects for Umami, Plausible, and PostHog and store API keys, site_id (Umami), tokens, and project keys in environment variables.
- Step 2: Configure tracking domains via environment variables (no hardcoding) and switch by environment.
- Step 3: Implement event emission using millisecond timestamps and JSON-safe properties; verify the script loads, apply consent checks, and implement exponential backoff on 429 (use /batch for PostHog when appropriate).
Best Practices
- Always timestamp events in milliseconds (Date.now()), not seconds.
- For Plausible, use site_id from the dashboard URL, not the domain name.
- Ensure event properties are JSON-serializable; avoid DOM elements and functions.
- Enforce rate limits with exponential backoff; batch PostHog via /batch, Umami/Plausible use single requests.
- Keep API keys in environment variables; never hardcode; gate tracking with consent and IP/geolocation checks.
Example Use Cases
- Umami integration on a marketing site using site_id and API key with millisecond timestamps.
- Plausible v2 setup using a Bearer token and site_id to stay within 600/hour limits.
- PostHog event streaming with individual sends and optional /batch for improved throughput.
- GDPR-compliant tracking with explicit EU consent and IP geolocation gating before events.
- Development environment with separate dev projects to prevent production data pollution.
