OrbitsDocs
esc
    Open Orbits
    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:

    1. 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.
    2. 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

    Terminal
    $ npm install @useorbits/analytics

    Then 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.

    app/layout.tsx
    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.

    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:

    TypeScript
    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 localhost the package logs to the console instead.

    Options

    <Analytics /> takes the same options as inject():

    OptionDefault
    beforeSendA 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.
    debugfalseLog 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:

    tsx
    <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
    VisitorsVisitors and page views over the range. A bounce is a visitor who saw one page
    Top pagesBy the route your framework named, or else the path with its ids grouped (/products/8412 is /products/[id])
    ReferrersOther sites that sent visitors. A visit nobody linked to has no referrer
    CountriesEmpty for now: countries show once Orbits starts looking up where visits come from
    DevicesThe kinds of device visitors used
    EventsYour 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=7dThe page's numbers: range is 24h, 7d (default) or 30d. Answers { "enabled": false } while it's off
    GET .../analytics/event?name=Signed%20up&range=7dOne 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.

    Was this page helpful?

    Updated