The complete developer reference: installation, configuration, goals and custom events, the REST API, webhooks, and the exact definitions behind every number on your dashboard.
Paste this into the <head> of your site. That's the whole installation, under 1KB, deferred, invisible to Core Web Vitals.
Fire a custom event from anywhere in your JavaScript, then define it as a goal in the dashboard:
Pull stats from the REST API with a token from Settings → API (Scale plan):
Every option is a data attribute on the script tag. The defaults are right for most sites; change them only when you have a reason.
| Attribute | Default | What it does |
|---|---|---|
| data-site | required | Your site ID from the dashboard. The only mandatory attribute. |
| data-spa | on | Automatically counts History-API route changes as pageviews. Set "off" to call window.bobray('pageview') yourself. |
| data-hash | off | Treats #/route hash changes as pageviews, for hash-routed apps. |
| data-outbound | on | Records clicks on links leaving your domain as an outbound event with the destination host. |
| data-downloads | on | Records clicks on common file links (pdf, zip, dmg, csv…) as a download event. |
| data-exclude | none | Comma-separated path patterns to never count, e.g. "/admin/*,/preview/*". |
Deeper guides: The tracking snippet · Single-page applications · Content-Security-Policy · Localhost & staging
An event is anything you fire from code. A goal is an event (or a URL visit) you've told the dashboard to treat as a conversion, giving you rates, funnels, and webhooks.
In Dashboard → Goals → New, a goal is either an event name (purchase) or a URL pattern (/thank-you). Chain up to eight goals into a funnel under Goals → Funnels to see stage-by-stage drop-off, for example /pricing → checkout-started → purchase. Goals and funnels are available on Growth and above.
The v1 API (Scale plan) returns the same figures as the dashboard, same time zone, same definitions, as clean JSON. Authenticate with a bearer token from Settings → API.
| Endpoint | Returns |
|---|---|
| GET /v1/stats | Headline aggregates: visitors, pageviews, avg. time, bounce rate for the period. |
| GET /v1/pages | Ranked pages with visitors and pageviews. Supports limit (≤1000) and offset. |
| GET /v1/sources | Ranked traffic sources grouped as Search, Direct, Social, Email, Referral. |
| GET /v1/goals | Goal totals with conversions and conversion_rate. |
Shared parameters: period (day, 7d, 30d, month, custom + from/to), and combinable filter expressions like page==/pricing;country==NL. Rate limit is 600 req/min per token with standard 429 + Retry-After. Full details: Authentication · Endpoints reference · Data export.
Goal completions, traffic-spike alerts, and report-ready events can POST to your endpoint seconds after they happen, signed, retried, and containing zero visitor-identifying data.
Verify the HMAC-SHA256 signature, expect at-least-once delivery with retries at 1/5/30 minutes, and make handlers idempotent. Full guide: Webhooks.
Analytics disagreements are usually definition disagreements. These are ours, stated plainly so your numbers are never a mystery.
| Metric | Definition |
|---|---|
| Pageview | One page load, or one route change in an SPA. Query-string-only changes don't count by default; known bots are filtered before counting. |
| Visitor / visit | Pageviews grouped by an anonymous, day-scoped token, derived without cookies and reset daily. Daily uniques are therefore conservative. |
| Avg. time | Median engaged seconds per visit, tab must be visible; medians resist the overnight-open-tab problem. |
| Bounce rate | Share of visits with exactly one pageview and no events. |
| Source | Referrer host grouped into Search / Direct / Social / Email / Referral, with UTM parameters taking precedence when present. See why referrers go missing. |
| Conversion rate | Goal completions ÷ visitors in the period, per goal. |
Drop-in plugins and packages for the tools you already use, each linking to its full setup guide.
Official plugin in the directory. Activate, paste your site ID, done, WooCommerce goals included.
One-click app install with automatic checkout goal tracking on the thank-you page.
A small npm package with a drop-in component and a typed useBobray() hook.
Paste the snippet into your site-wide code injection, the plain-snippet guide covers both.
Send goal completions to Slack, Zapier, or your own endpoint, signed and retried.
One-off CSVs from any view, or scheduled exports straight to your warehouse.
Our support team answers technical questions within one business day, and then we fix the docs.