Configuration

Every option for the SDK. Most have sensible defaults.

AnalyticsConfig

The main config object you pass to the <Analytics /> component or createAnalytics.

interface AnalyticsConfig {
  apiKey: string;
  host?: string;
  flushAt?: number;
  flushInterval?: number;
  sessionTimeout?: number;
  cookieDomain?: string;
  debug?: boolean;
  respectDNT?: boolean;
  maxRetries?: number;
  errors?: ErrorCaptureConfig;
}

Prop

Type

ErrorCaptureConfig

Config for automatic error tracking. Only matters if you're using it.

interface ErrorCaptureConfig {
  enabled?: boolean;
  captureConsoleErrors?: boolean;
  captureNetworkErrors?: boolean;
  maxBreadcrumbs?: number;
  beforeSend?: (payload: ErrorPayload) => ErrorPayload | null;
}

Prop

Type

Example Configurations

The "I Just Want It To Work"

<Analytics apiKey="tif_xxx" />

Done. Defaults are fine for most people.

The "I'm Debugging Locally"

<Analytics
  apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!}
  debug={true}
  config={{
    flushAt: 1,
    flushInterval: 1000,
  }}
/>

Events show up in console and send immediately.

The "Production Ready"

<Analytics
  apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!}
  config={{
    errors: {
      enabled: true,
      captureConsoleErrors: false,
      captureNetworkErrors: true,
      maxBreadcrumbs: 50,
      beforeSend: (payload) => {
        if (payload.message.includes('ResizeObserver')) return null;
        return payload;
      },
    },
  }}
/>

Error tracking enabled, ResizeObserver noise filtered.

Cross-Subdomain Tracking

<Analytics
  apiKey="tif_xxx"
  config={{
    cookieDomain: '.example.com',
  }}
/>

Tracks across app.example.com and www.example.com.

Longer Sessions

<Analytics
  apiKey="tif_xxx"
  config={{
    sessionTimeout: 7200000,
  }}
/>

2 hour timeout instead of default 30 minutes. Good for apps where users stay logged in all day.

Environment-Specific Config

Here's a pattern that works well:

app/layout.tsx

import { Analytics } from '@thisbefine/analytics/next';

const isDev = process.env.NODE_ENV === 'development';

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        {children}
        <Analytics
          apiKey={process.env.NEXT_PUBLIC_THISBEFINE_API_KEY!}
          debug={isDev}
          config={{
            flushAt: isDev ? 1 : 20,
            flushInterval: isDev ? 1000 : 10000,
            errors: {
              enabled: !isDev,
              captureNetworkErrors: !isDev,
            },
          }}
        />
      </body>
    </html>
  );
}

Self-Hosting?

If you're running your own Thisbefine instance:

<Analytics
  apiKey="tif_xxx"
  host="https://analytics.yourcompany.com"
/>

When self-hosting, make sure your API implements the same endpoints. Check the API Reference for details.

What Gets Stored Locally

The SDK uses localStorage to persist user identity and session state:

Key	What It Is
`tif_anonymous_id`	Random ID for non-logged-in users
`tif_user_id`	User ID after `identify()`
`tif_user_traits`	Traits from `identify()`
`tif_account_id`	Account ID from `group()`
`tif_account_traits`	Account traits
`tif_session_id`	Current session
`tif_last_activity`	For session timeout calculation
`tif_opt_out`	Whether user opted out

If you clear localStorage, you'll lose the anonymous ID. The user will get a new one and their history won't be linked. This is fine (heh) for most cases but worth knowing.

Configuration

On this page