SDK Reference

The Tally SDK is automatically installed when you merge the generated PR. This page covers manual usage for advanced use cases.

Installation

npm install @tally-analytics/sdk # or pnpm add @tally-analytics/sdk # or yarn add @tally-analytics/sdk

Quick Start: App Router (Next.js 13+)

For Next.js App Router, use the AnalyticsAppRouter component in your root layout:

// app/layout.tsx
'use client';

import { AnalyticsAppRouter, init } from '@tally-analytics/sdk';

// Initialize once at the top level
init({ projectId: 'proj_abc123' });

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <AnalyticsAppRouter />
      </body>
    </html>
  );
}

Quick Start: Pages Router

For Next.js Pages Router, use the AnalyticsPagesRouter component in your _app.tsx:

// pages/_app.tsx
import { AnalyticsPagesRouter, init } from '@tally-analytics/sdk';
import type { AppProps } from 'next/app';

// Initialize once at the top level
init({ projectId: 'proj_abc123' });

export default function App({ Component, pageProps }: AppProps) {
  return (
    <>
      <Component {...pageProps} />
      <AnalyticsPagesRouter />
    </>
  );
}

API Reference

`init(options)`

Initialize the SDK. Must be called before any tracking.

init({
  projectId: 'proj_abc123',  // Required: Your project ID
  respectDNT: true,          // Optional: Honor Do Not Track (default: true)
  debug: false               // Optional: Log events to console (default: false)
});

Option	Type	Default	Description
`projectId`	string	—	Your Tally project ID (required)
`respectDNT`	boolean	true	If true, no events are sent when Do Not Track is enabled
`debug`	boolean	false	If true, logs events to the browser console

`trackPageView(path?)`

Manually track a page view. Usually not needed—the React components handle this automatically on route changes.

import { trackPageView } from '@tally-analytics/sdk';

// Track current page
await trackPageView();

// Track a specific path
await trackPageView('/custom/path');

`identify(userId)`

Associate events with a user ID. Call this after a user logs in to link anonymous sessions to their account.

import { identify } from '@tally-analytics/sdk';

// After user logs in
identify('user_12345');

// Or with an email hash
identify('abc123def456');

Note: The user ID is stored in memory only and is not persisted across page reloads. Call identify()on each page load after authentication.

`isEnabled()`

Check if tracking is currently enabled.

import { isEnabled } from '@tally-analytics/sdk';

if (isEnabled()) {
  console.log('Tracking is active');
} else {
  console.log('Tracking is disabled (DNT or not initialized)');
}

Returns false if:

init() has not been called
Running on the server (SSR)
Do Not Track is enabled and respectDNT is true

Do Not Track (DNT)

By default, Tally respects the browser's Do Not Track setting. When DNT is enabled, no events are sent.

To disable DNT respect (not recommended):

init({
  projectId: 'proj_abc123',
  respectDNT: false  // Will track even with DNT enabled
});

Session Tracking

Tally uses a first-party cookie to track sessions. The cookie contains only an anonymous UUID—no personal information is stored.

Cookie name: tally_session
Expiry: 30 minutes of inactivity
Scope: First-party only (your domain)

This approach is GDPR-friendly and does not require a consent banner in most jurisdictions, as it's first-party analytics with no personal data collection.

Troubleshooting

Events not appearing in dashboard

Check that init() is called before any tracking
Verify your project ID is correct
Check if Do Not Track is enabled in your browser
Enable debug mode: init({{ projectId: "...", debug: true }})
Check the browser console for errors

SSR/Hydration issues

The SDK is client-side only. Make sure the React components are used in a client component (add 'use client' directive) or in a file that's only imported client-side.