Plausible Analytics collector

Server-side analytics collector implementing analytics.Collector against the Plausible Analytics Events API.

Overview

Plausible is a privacy-first analytics service. It uses no cookies and no personal data, and ships a single self-contained event API that runs against either Plausible Cloud or a self-hosted instance. Because this collector runs server-side, events flow from the Piko process directly to Plausible. There is no client-side script for ad blockers to strip. Per-event headers (User-Agent, X-Forwarded-For) carry the visitor signals Plausible needs for device and geographic attribution.

A batcher buffers events and flushes when the batch reaches WithBatchSize (default 10) or the WithFlushInterval timer fires (default 5 seconds). Plausible has no batch endpoint, so the collector still issues one HTTP POST per event. The collector reuses the shared piko analytics machinery, the generic batcher, retry, and the gobreaker circuit breaker, instead of reimplementing delivery. The same resilience options behave the way they do for every other collector. Page-view events, server-action events, and custom events all map onto Plausible's event model, including its built-in revenue field for e-commerce tracking. All public methods are safe for concurrent use.

The collector is pure Go. It carries no build tags and no CGO dependency, so it runs the same way in compiled and interpreted (dev-i) run modes.

Requirements

  • A Plausible Cloud account or a self-hosted Plausible instance with the site domain registered.
  • Network egress to plausible.io (Plausible Cloud) or your self-hosted endpoint.

Plausible's Events API uses domain-based identification. It needs no API key. The domain must match a site configured in your Plausible account.

Configuration

import (
    "time"

    "piko.sh/piko/wdk/analytics"
    "piko.sh/piko/wdk/analytics/analytics_collector_plausible"
)

collector, err := analytics_collector_plausible.NewCollector(
    "example.com", // required; site domain registered in Plausible
    analytics_collector_plausible.WithBatchSize(20),
    analytics_collector_plausible.WithFlushInterval(5*time.Second),
)
if err != nil {
    return err
}

Self-hosted instance:

collector, err := analytics_collector_plausible.NewCollector("example.com",
    analytics_collector_plausible.WithEndpoint("https://analytics.example.com"),
)

Resilience options:

collector, err := analytics_collector_plausible.NewCollector("example.com",
    analytics_collector_plausible.WithRetry(analytics.RetryConfig{
        MaxRetries: 3,
    }),
    analytics_collector_plausible.WithCircuitBreaker(analytics.CircuitBreakerConfig{
        MaxConsecutiveFailures: 5,
        Timeout:                30 * time.Second,
    }),
)

Bootstrap

Backend analytics collectors register through WithBackendAnalytics instead of the named-provider pattern. Registering at least one collector installs the analytics middleware (after auth, before rate limiting), which fires page-view events on every request. Wiring is a single bootstrap option with no glue code.

ssr := piko.New(
    piko.WithBackendAnalytics(collector),
)

Bootstrap owns the collector lifecycle. It starts the analytics service, registers the collector for graceful shutdown, and flushes buffered events on close. Do not call Start, Flush, or Close on the collector yourself.

See also

Other analytics integrations:

Framework docs:

External: