Cabin Analytics

https://docs.withcabin.com
Admin
Cabin is a privacy-first, carbon-conscious, and cookieless web analytics service designed as a...
Tokens:25,553
Snippets:237
Trust Score:9.4
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Gatsby: Install gatsby-script and add Script to layout

Source: https://docs.withcabin.com/install

Use the Gatsby Script API: install `gatsby-script` first, then use the `Script` component in your layout component (typically `src/components/layout.js`). The `strategy="postHydrate"` with `async` and `defer` loads the tracking script after hydration.

```bash
npm install gatsby-script
```

```jsx
import React from "react"
import { Script } from "gatsby"

export default function Layout({ children }) {
  return (
    <>
      {children}
      <Script
        src="https://scripts.withcabin.com/hello.js"
        strategy="postHydrate"
        async
        defer
      />
    </>
  )
}
```

--------------------------------

### Example JSON response from /analytics

Source: https://docs.withcabin.com/api

Example response object showing the query echo and the beginning of the aggregated data structure. The response includes a query object and fields available with the core scope.

```json
{
  query: {
    domain: "example.com",
    date_from: "2025-01-01",
    date_to: "2025-02-01",
    scope: "core,pages,referrals",
    limit_lists: 10
  },

  /* Available with scope: core */
}
```

--------------------------------

### validate_installation

Source: https://docs.withcabin.com/mcp-tools

Validates the installation of the tracking script on a domain.

```APIDOC
## validate_installation

### Description
Check whether the Cabin tracking script is correctly installed on one of your domains.

### Method
READ

### Parameters
- `domain` (string) - Required - The domain to check

```

--------------------------------

### Install Cabin with HTML script tag before </body>

Source: https://docs.withcabin.com/install

Place this one-line script tag before the closing </body> tag on your site. It loads the Cabin analytics script asynchronously and is identical for all platforms.

```html
<script async defer src="https://scripts.withcabin.com/hello.js"></script>
```

--------------------------------

### Common event tracking examples

Source: https://docs.withcabin.com/events

Common event tracking examples: PDF downloads, video plays, and form submissions. The form uses the onsubmit attribute to call cabin.event() and returns true to allow submission.

```html
<!-- Track PDF downloads -->
<a href="report.pdf" data-cabin-event="Download Report">Download Annual Report</a>

<!-- Track video plays -->
<button data-cabin-event="Play Tutorial Video">Play Video</button>

<!-- Track form submissions -->
<form onsubmit="cabin.event('Newsletter Signup'); return true;">
    <!-- form fields -->
    <button type="submit">Subscribe</button>
</form>
```

--------------------------------

### API response example with referrals and events

Source: https://docs.withcabin.com/api

Example JSON response from the Cabin analytics API showing the referrals array with source, page_views, unique_visitors, has_utm, and page_views_percentage fields, and the events array (available with scope: events) with name, count, percentage, and pages breakdown.

```json
{
  referrals: [
    {
      source: "Google",
      page_views: 259,
      unique_visitors: 197,
      has_utm: false,
      page_views_percentage: 0.39
    },
    {
      source: "LinkedIn",
      page_views: 252,
      unique_visitors: 136,
      has_utm: false,
      page_views_percentage: 0.38
    },
    {
      source: "com.linkedin.android",
      page_views: 34,
      unique_visitors: 18,
      has_utm: false,
      page_views_percentage: 0.05
    },
    // ...
  ],

  /* Available with scope: events */

  events: [
    {
      name: "signup button (header)",
      count: 14,
      percentage: 0.1129,
      pages: [
        {
          path: "/",
          count: 13,
          percentage: 0.9286
        },
        {
          path: "/pricing",
          count: 1,
          percentage: 0.0714
        }
      ]
    },
    // ...
  ]
}
```

--------------------------------

### Cabin API analytics response example

Source: https://docs.withcabin.com/api

Example response body for the Cabin API analytics endpoint. Shows summary metrics, daily data, screen sizes, devices, browsers, operating systems, countries, languages, traffic sources, AI agents, energy data, per-page details, and site-wide scroll depth. The `energy` and `pages` fields are available with the `pages` scope; the trailing comment indicates the `referrals` scope is also available.

```json
{
  summary: {
    page_views: 1959,
    unique_visitors: 1165,
    bounces: 817,
    bounce_rate: 0.29871244635193134
  },
  daily_data: [
    {
      timestamp: 1735689600000,
      page_views: 22,
      unique_visitors: 16,
      bounces: 12,
      bounce_rate: 0.75
    },
    {
      timestamp: 1735776000000,
      page_views: 29,
      unique_visitors: 26,
      bounces: 23,
      bounce_rate: 0.88
    },
    {
      timestamp: 1735862400000,
      page_views: 24,
      unique_visitors: 16,
      bounces: 13,
      bounce_rate: 0.81
    }
  ],
  screen_sizes: {
    small: 38,
    medium: 372,
    large: 463
  },
  devices: {
    desktop: 873,
    mobile: 288,
    tablet: 4,
    smart_tv: 0,
    console: 0,
    wearable: 0
  },
  browsers: [
    {
      name: "Chrome",
      value: 718
    },
    {
      name: "WebKit",
      value: 117
    },
    {
      name: "Firefox",
      value: 85
    }
  ],
  operating_systems: [
    {
      name: "Windows",
      value: 467
    },
    {
      name: "Mac OS",
      value: 365
    },
    {
      name: "iOS",
      value: 223
    }
    // ...
  ],
  countries: [
    {
      code: "GB",
      value: 362
    },
    {
      code: "US",
      value: 263
    },
    {
      code: "JP",
      value: 41
    }
    // ...
  ],
  languages: [
    {
    code: "en",
      value: 887
    },
    {
      code: "ja",
      value: 37
    },
    {
      code: "ru",
      value: 32
    }
    // ...
  ],
  traffic_sources: {
    email: 0,
    search: 217,
    social: 151,
    unknown: 789
  },
  ai_agents: [
    {
      name: "ChatGPT",
      hits: 34,
      percentage: 0.9444
    },
    {
      name: "Claude",
      hits: 2,
      percentage: 0.0556
    }
  ],

  /* Available with scope: pages */

  energy: {
    page_count: 22,
    green_hosting: {
      url: "nicmulvaney.com",
      hosted_by: "Cloudflare",
      hosted_by_website: "https://www.cloudflare.com",
      partner: null,
      green: true,
      hosted_by_id: 779,
      modified: "2025-03-17T20:24:22",
      supporting_documents: [
        {
          id: 18,
          title: "Blog post - The Climate and Cloudflare",
          link: "https://blog.cloudflare.com/the-climate-and-cloudflare/"
        },
        {
          id: 1264,
          title: "Cloudflare 2023 Emissions Inventory",
          link: "https://s3.nl-ams.scw.cloud/tgwf-web-app-live/uploads/Cloudflare_2023_Emissions_Inventory.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=SCWT1WBAW6NZ5SW5GYJ8%2F20250317%2Fnl-ams%2Fs3%2Faws4_request&X-Amz-Date=20250317T202736Z&X-Amz-Expires=3600&X-Amz-SignedHeaders=host&X-Amz-Signature=0d3b2ffd9a885dbc41193e0e72bdee9c4ee8cf37671af3d092453578cc5a179c"
        }
      ]
    },
    average_time_spent_ms: 122892,
    average_co2_grams: 0.0708,
    total_co2_grams: 138.65,
    total_distance_km: 0.55,
    total_kettles: 4,
    transferred_bytes: 1145572683,
    total_bytes: 22060595,
    duration_total_ms: 240746383,
    duration_count: 1272
  },
  pages: [
    {
      path: "/page/1",
      page_views: 271671,
      unique_visitors: 243070,
      average_duration_seconds: 123,
      total_bytes: 8.2,
      co2_grams: 538,
      page_views_percentage: 0.12,
      scroll_depth: {
        average_percentage: 46.2,
        measured_visits: 1840,
        reached_at_least: [
          { percent: 0, visitors_percentage: 100 },
          { percent: 10, visitors_percentage: 88.37 },
          { percent: 20, visitors_percentage: 79.08 },
          { percent: 30, visitors_percentage: 73.75 },
          { percent: 40, visitors_percentage: 69.18 },
          { percent: 50, visitors_percentage: 65 },
          { percent: 60, visitors_percentage: 57.83 },
          { percent: 70, visitors_percentage: 52.61 },
          { percent: 80, visitors_percentage: 46.63 },
          { percent: 90, visitors_percentage: 38.86 },
          { percent: 100, visitors_percentage: 22.01 }
        ]
      }
    },
    {
      path: "/page/2",
      page_views: 167111,
      unique_visitors: 150073,
      average_duration_seconds: 147,
      total_bytes: 4.82,
      co2_grams: 222.6,
      page_views_percentage: 0.08
    },
    {
      path: "/page/3",
      page_views: 106361,
      unique_visitors: 93743,
      average_duration_seconds: 97,
      total_bytes: 4.82,
      co2_grams: 133.4,
      page_views_percentage: 0.05
    },
    // ...
  ],

  // Site-wide, summed over every page, not only the ones in `pages`.
  scroll_depth: {
    average_percentage: 41.8,
    measured_visits: 94211,
    reached_at_least: [
      { percent: 0, visitors_percentage: 100 },
      // ... one row per decile ...
      { percent: 100, visitors_percentage: 18.4 }
    ]
  },

  /* Available with scope: referrals */
}
```

--------------------------------

### Curl request to /analytics endpoint

Source: https://docs.withcabin.com/api

Example curl command to fetch analytics data for a domain between two dates. Replace YOUR_API_KEY with your actual API key and adjust domain and dates as needed.

```bash
curl -X GET "https://api.withcabin.com/v1/analytics?domain=example.com&date_from=2025-01-01&date_to=2025-02-01&scope=core&limit_lists=20" -H "x-api-key: YOUR_API_KEY"
```

--------------------------------

### Combined content and scroll root example

Source: https://docs.withcabin.com/scroll-depth

This HTML snippet shows a typical app layout with a fixed header, a scrollable div marked with data-cabin-scroll-root, and an article marked with data-cabin-content. The footer is inside the scroll root but excluded from content measurement.

```html
<body>
  <header>fixed, never scrolls</header>

  <div data-cabin-scroll-root>
    <!-- the bit that moves -->
    <article data-cabin-content>
      <!-- the bit that counts -->
    </article>
    <footer>tall, shouldn't count towards the reading</footer>
  </div>
</body>
```

--------------------------------

### Resume tracking with cabin.blockMe(false)

Source: https://docs.withcabin.com/block-visits

Run this command to resume tracking your visits. Alternatively, clear the site's Local Storage to remove the block.

```javascript
cabin.blockMe(false)
```

--------------------------------

### Cursor: MCP config for Cabin

Source: https://docs.withcabin.com/mcp-connect

Add this JSON to your MCP config file at `~/.cursor/mcp.json`. Restart Cursor, then open Settings → MCP to see the Cabin server and complete OAuth.

```json
{
  "mcpServers": {
    "cabin": {
      "type": "http",
      "url": "https://withcabin.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Cabin MCP server in Zed settings

Source: https://docs.withcabin.com/mcp-connect

Add this configuration to Zed settings (opened with cmd+,) to enable the Cabin MCP server. Zed automatically triggers the OAuth flow when the server is first used.

```json
{
  "context_servers": {
    "cabin": {
      "url": "https://withcabin.com/mcp"
    }
  }
}
```

--------------------------------

### GET /v1/analytics

Source: https://docs.withcabin.com/api

Retrieves aggregated analytics data for a specified domain and date range. Supports optional scopes for additional data such as pages, referrals, and events.

```APIDOC
## [GET] /v1/analytics

### Description
Retrieves aggregated analytics data for a specified domain and date range. Supports optional scopes for additional data such as pages, referrals, and events.

### Method
GET

### Endpoint
https://api.withcabin.com/v1/analytics

### Parameters
#### Query Parameters
- **domain** (string) - Required - The domain name for which you want to retrieve analytics data.
- **date_from** (string) - Required - The start date for the data (format: YYYY-MM-DD).
- **date_to** (string) - Required - The end date for the data (format: YYYY-MM-DD).
- **scope** (string) - Optional - The scope of the data. Can contain any combination of `core,pages,referrals,events`. Default: `core`.
- **limit_lists** (number) - Optional - The number of items to return in each list. Values above `250` aren't rejected, but responses get large and slow, so treat 250 as the practical ceiling. This affects `countries`, `languages`, `browsers`, `operating_systems`, `devices`, `screen_sizes`, `pages` and `referrals`. Default: `50`.

### Request Example
```bash
curl -X GET "https://api.withcabin.com/v1/analytics?domain=example.com&date_from=2025-01-01&date_to=2025-02-01&scope=core&limit_lists=20" -H "x-api-key: YOUR_API_KEY"
```

### Response
#### Success Response (200)
- **query** (object) - The query parameters echoed back.
- **query.domain** (string) - The domain name.
- **query.date_from** (string) - The start date.
- **query.date_to** (string) - The end date.
- **query.scope** (string) - The scope used.
- **query.limit_lists** (number) - The limit for lists.
- Additional fields depend on the requested scope. For example, with `scope=core`, fields like `summary` and `ai_agents` may be present.

#### Response Example
```json
{
  "query": {
    "domain": "example.com",
    "date_from": "2025-01-01",
    "date_to": "2025-02-01",
    "scope": "core,pages,referrals",
    "limit_lists": 10
  }
}
```
```

--------------------------------

### Configure Cabin MCP server in Codex config.toml

Source: https://docs.withcabin.com/mcp-connect

Alternative configuration for Codex by editing `~/.codex/config.toml` directly. Requires Codex CLI 0.121.0 or newer for Streamable HTTP MCP servers.

```toml
[mcp_servers.cabin]
url = "https://withcabin.com/mcp"
```

--------------------------------

### Find share of visitors reading past halfway mark

Source: https://docs.withcabin.com/api

JavaScript snippet that finds the share of measured visits that reached at least 50% scroll depth using the cumulative reached_at_least array. Logs visitors_percentage, which is 65 in the example.

```javascript
// "what share read past the halfway mark?"
const half = page.scroll_depth.reached_at_least.find(r => r.percent === 50)
console.log(half.visitors_percentage) // 65
```

--------------------------------

### OpenCode MCP server configuration for Cabin

Source: https://docs.withcabin.com/mcp-connect

Add this configuration to your OpenCode config to connect to the Cabin MCP server. OpenCode handles OAuth automatically, opening your browser on first connection. You can also trigger authentication manually with `opencode mcp auth cabin`.

```json
{
  "mcpServers": {
    "cabin": {
      "type": "remote",
      "url": "https://withcabin.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Cabin MCP server in Cline settings

Source: https://docs.withcabin.com/mcp-connect

Add this configuration to cline_mcp_settings.json (opened via the MCP icon in Cline's top bar) to enable the Cabin MCP server. After saving, click the Authenticate button to complete the OAuth flow.

```json
{
  "mcpServers": {
    "cabin": {
      "url": "https://withcabin.com/mcp",
      "type": "streamableHttp",
      "disabled": false,
      "autoApprove": [],
      "timeout": 60
    }
  }
}
```

--------------------------------

### Svelte/SvelteKit: Add tracking script to app.html

Source: https://docs.withcabin.com/install

Modify the `src/app.html` file in Svelte/SvelteKit to include the tracking script before the closing `</body>` tag. This is the full HTML structure with the script added.

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width" />
    %sveltekit.head%
  </head>
  <body data-sveltekit-preload-data="hover">
    <div style="display: contents">%sveltekit.body%</div>
    <script async defer src="https://scripts.withcabin.com/hello.js"></script>
  </body>
</html>
```

--------------------------------

### Configure Cabin MCP server in Windsurf mcp_config.json

Source: https://docs.withcabin.com/mcp-connect

Configures the Cabin MCP server for Windsurf using the `mcp-remote` proxy to handle OAuth. Requires Node.js. On first connection, `mcp-remote` opens your browser to complete the OAuth flow.

```json
{
  "mcpServers": {
    "cabin": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://withcabin.com/mcp"]
    }
  }
}
```

--------------------------------

### create_domain

Source: https://docs.withcabin.com/mcp-tools

Creates a new domain in the account.

```APIDOC
## create_domain

### Description
Add a new domain to your account. Returns the dashboard URL and the tracking-script snippet to install.

### Method
WRITE

### Parameters
- `domain` (string) - Required - The domain to add (no protocol or path)
- `tz` (string) - Optional - IANA timezone for the analytics, e.g. `Europe/London` (default `UTC`)

```

--------------------------------

### Configure Cabin MCP server in VS Code mcp.json

Source: https://docs.withcabin.com/mcp-connect

Adds the Cabin MCP server to VS Code Copilot by placing this in `.vscode/mcp.json`. On first use, VS Code opens your browser to complete the OAuth flow.

```json
{
  "servers": {
    "cabin": {
      "type": "http",
      "url": "https://withcabin.com/mcp"
    }
  }
}
```

--------------------------------

### Configure Cabin MCP server in Gemini CLI settings

Source: https://docs.withcabin.com/mcp-connect

Add this configuration to ~/.gemini/settings.json to enable the Cabin MCP server in the Gemini CLI. After saving, run /mcp auth cabin to complete the OAuth flow. The Gemini web app does not support custom MCP servers.

```json
{
  "mcpServers": {
    "cabin": {
      "url": "https://withcabin.com/mcp"
    }
  }
}
```

--------------------------------

### Block your own browser with cabin.blockMe(true)

Source: https://docs.withcabin.com/block-visits

Run this command in the browser's Developer Console to prevent Cabin from logging your visits. The flag is saved in the site's Local Storage and covers one site, one browser, one device. In a private window, the flag lasts only until the window is closed.

```javascript
cabin.blockMe(true)
```

--------------------------------

### Nuxt: Add tracking script to app.head in nuxt.config.js

Source: https://docs.withcabin.com/install

Add the tracking script to Nuxt by editing the `nuxt.config.js` file and adding the script to `app.head`. The script includes both `defer` and `async` attributes.

```js
export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://scripts.withcabin.com/hello.js',
          defer: true,
          async: true
        }
      ]
    }
  }
})
```

--------------------------------

### Replace tracking script with custom domain

Source: https://docs.withcabin.com/bypass-ad-blockers

Replace the default tracking script with the custom domain version after setting up your CNAME record and validating the domain.

```html
<script src="https://scripts.withcabin.com/hello.js" async defer></script>
```

```html
<script src="https://cabin.yourdomain.com/hello.js" async defer></script>
```

--------------------------------

### Add Cabin tracking script to Next.js RootLayout

Source: https://docs.withcabin.com/install

Edit app/layout.js or app/layout.tsx to import the Cabin script in the RootLayout component, using the Next.js Script component with afterInteractive strategy.

```jsx
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <head>
        <Script
          src="https://scripts.withcabin.com/hello.js"
          strategy="afterInteractive"
        />
      </head>
      <body>
        {children}
      </body>
    </html>
  )
}

```

--------------------------------

### Exclude IP addresses and ranges (CIDR notation)

Source: https://docs.withcabin.com/block-visits

Enter one IP address or range per line in the 'Exclude IP addresses' field. IPv4 and IPv6 are supported, and ranges use CIDR notation. Up to 30 entries per site are allowed.

```plaintext
203.0.113.7
203.0.113.0/24
2001:db8::/32
```
Tokens:
Raw