ObserveAnalytics
Analytics
Visitors, top pages, referrers, devices and your own custom events, counted without cookies and without storing IP addresses. Add `@useorbits/analytics` to your app and turn Analytics on for the project. Pro plan.
How it works
Analytics has two halves:
- A switch on the project. Turning Analytics on tells your project's production addresses to serve Orbits' script,
/_orbits/analytics.js, and to record what it sends. - A small package in your app,
@useorbits/analytics. It loads that script from your site's own address. The script counts each page a visitor sees, single-page navigations included, and the custom events you send.
The script sends to /_orbits/e on your own host, so there is nothing cross-site to allow and nothing for your app to handle: those requests never reach your app and don't count as its requests. Only production deployments are counted, never previews.
1. Turn it on
Open the project, choose Analytics and press Turn on Analytics. Owners, admins and members can turn it on or off; viewers can't. The project's addresses pick the change up within seconds.
Until the first visit arrives, the page says Waiting for the first visit and shows the snippet to add. To turn it off later, use Turn it off at the foot of the page. While it's off, the script isn't served and nothing is recorded.
2. Install the package
$ npm install @useorbits/analyticsThen add it once, in the place your framework renders on every page.
Put <Analytics /> in the root layout. Pages are grouped by the route that served them (/blog/[slug]), not by each address.
import { Analytics } from "@useorbits/analytics/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en">
<body>
{children}
<Analytics />
</body>
</html>
);
}With the Pages Router, render it in pages/_app.tsx instead.
For Vite, React Router, TanStack Router, Remix and other React apps:
import { Analytics } from "@useorbits/analytics/react";
export function App() {
return (
<>
<Routes />
<Analytics />
</>
);
}<script setup lang="ts">
import { Analytics } from "@useorbits/analytics/vue";
</script>
<template>
<RouterView />
<Analytics />
</template>import { injectAnalytics } from "@useorbits/analytics/sveltekit";
injectAnalytics();Pages are grouped by SvelteKit's route (/products/[id]).
---
import Analytics from "@useorbits/analytics/astro";
---
<Analytics />Astro 5 names the route that served each page, and View Transitions are counted too.
With a bundler, call inject() once in code that runs in the browser:
import { inject } from "@useorbits/analytics";
inject();Without one, add the script itself. It's the same script the package loads:
<script defer src="/_orbits/analytics.js"></script>Deploy to production, and visits show on the Analytics tab within a minute.
3. Send custom events
Count what matters to you, like sign-ups or orders, from anywhere in the browser:
import { track } from "@useorbits/analytics";
track("Signed up", { plan: "pro", seats: 3 });- Properties are flat: strings, numbers, booleans or
null, up to 20 of them. - Event names, property keys and string values are cut at 255 characters.
The Events panel lists events by how often they were sent. Pick one to see the properties sent with it, each with its ten commonest values. Events can be sent from the browser only; there is no server-side track() yet.
To count a page view yourself, such as a step in a wizard that keeps the same address, call pageview({ path: "/checkout/payment" }).
What counts as a page view
- The page a visitor lands on: counted, with the referrer if there is one.
- Each
history.pushState, and back or forward: counted, so client-side routing is covered. The Next.js, SvelteKit and Astro components report their own navigations instead, with the route. - The same path twice in a row: counted once. Query strings and hashes are left out.
- Browsers driven by a script, crawlers, bots and link previews: not counted.
- Development: nothing is sent. In a dev build or on
localhostthe package logs to the console instead.
Options
<Analytics /> takes the same options as inject():
| Option | Default | |
|---|---|---|
beforeSend | A function that gets each page view and event before it's sent. Return it, changed or not, or null to drop it. | |
mode | "auto" | "development" logs to the console instead of sending; "auto" is development in a dev build or on localhost. |
debug | false | Log each page view and event the script sends. |
scriptSrc | "/_orbits/analytics.js" | Where the script is loaded from. |
endpoint | "/_orbits/e" | Where page views and events go. |
Use beforeSend to keep private pages and codes out of your numbers:
<Analytics
beforeSend={(event) => {
if (event.url.includes("/admin")) return null;
return { ...event, url: event.url.replace(/\/invite\/[^/]+/, "/invite/[code]") };
}}
/>The Astro component can't take a function: set window.orbitsAnalyticsBeforeSend before it renders instead.
Reading the page
Pick a Time range: 24 hours (by the hour), 7 days or 30 days (by the Lagos day). Each is compared with the span before it, such as today against yesterday.
| Panel | |
|---|---|
| Visitors | Visitors and page views over the range. A bounce is a visitor who saw one page |
| Top pages | By the route your framework named, or else the path with its ids grouped (/products/8412 is /products/[id]) |
| Referrers | Other sites that sent visitors. A visit nobody linked to has no referrer |
| Countries | Empty for now: countries show once Orbits starts looking up where visits come from |
| Devices | The kinds of device visitors used |
| Events | Your custom events, most sent first |
Lists keep their top ten. Any member of the team can read the page.
Privacy: what is collected
- No cookies, so there is no cookie banner to add for Analytics.
- No IP addresses and no browser strings are stored.
- A visitor is a hash that changes every day. It is made from a secret, the date in Lagos, the project, the visitor's address and their browser, and only the hash is kept. The same person counts once a day, and can't be followed from one day to the next, or from one project to another.
- Query strings and hashes are left out of the page address.
- Bots, link previews, scripts and headless browsers are dropped.
- No user ids. Orbits doesn't keep an id for a visitor in the browser.
From the API
| Call | |
|---|---|
GET /v1/teams/{team}/projects/{project}/analytics?range=7d | The page's numbers: range is 24h, 7d (default) or 30d. Answers { "enabled": false } while it's off |
GET .../analytics/event?name=Signed%20up&range=7d | One custom event, with how often it was sent, by how many visitors, and its properties |
PUT .../analytics with { "enabled": true } | Turn it on or off. On Free, turning it on is 402 with code: plan_required |
See API › Insights.