@octalen/sdk

Tiny browser SDK for Octalen pageview analytics.

Install

npm install @octalen/sdk

Quickstart

import { initOctalen } from "@octalen/sdk";

const octalen = initOctalen({
  siteId: "site_xxx",
});

octalen.pageview();

By default, Octalen tracks the first pageview and SPA navigations automatically.

Script Tag Or SDK

Use the script tag for the simplest install:

<script defer src="https://collector.octalen.com/t.js" data-site="site_xxx"></script>

Use this SDK when you want a package-based integration:

initOctalen({ siteId: "site_xxx" });

Do not use both on the same page, or pageviews may be counted twice. The SDK warns and no-ops in debug mode if it detects the script integration.

Next.js Direct Mode

"use client";

import { initOctalen } from "@octalen/sdk";
import { useEffect } from "react";

export function Analytics() {
  useEffect(() => {
    const octalen = initOctalen({ siteId: "site_xxx" });
    return () => octalen.destroy();
  }, []);

  return null;
}

React users can install @octalen/react for the built-in <Analytics /> wrapper.

Next.js Proxy Mode

initOctalen({
  siteId: "site_xxx",
  endpoint: "/api/octalen/event",
});

Example App Router route:

export async function POST(request: Request) {
  const body = await request.text();

  return fetch("https://collector.octalen.com/e", {
    method: "POST",
    headers: { "Content-Type": "text/plain" },
    body,
  });
}

Options

initOctalen({
  siteId: "site_xxx",
  endpoint: "https://collector.octalen.com/e",
  autoPageviews: true,
  captureOnLocalhost: false,
  debug: false,
});

What Data Is Sent

The SDK sends the same pageview payload accepted by the Octalen collector:

{
  "s": "site_xxx",
  "u": "https://example.com/current-page",
  "r": "https://referrer.example",
  "w": 1280,
  "e": "pageview"
}

Custom events are intentionally not part of V1.

Size Check

bun run --filter=@octalen/sdk size

The script prints both minified and gzip size, and fails if the gzip bundle exceeds 1024 bytes.