Quickstart

Get behavioral analytics running in your app in three steps.

Install

npmpnpmyarn

npm install @hanzo/insights

pnpm add @hanzo/insights

yarn add @hanzo/insights

Initialize

import insights from '@hanzo/insights'

insights.init('your-project-api-key', {
  api_host: 'https://insights.hanzo.ai',
  autocapture: true,
  capture_pageview: true,
  capture_pageleave: true,
})

Get your project API key from insights.hanzo.ai → Project Settings → API Keys.

Capture Events

Autocapture handles clicks, form submissions, and pageviews automatically. For custom events:

// Track a custom event
insights.capture('signup_completed', {
  plan: 'pro',
  source: 'pricing_page',
})

// Identify a user
insights.identify('user-123', {
  email: '[email protected]',
  plan: 'pro',
})

Open insights.hanzo.ai to see events flowing in real-time.

Framework-Specific Setup

React

npm install @hanzo/insights @hanzo/insights-react

import { InsightsProvider } from '@hanzo/insights-react'

function App() {
  return (
    <InsightsProvider
      apiKey="your-project-api-key"
      options={{ api_host: 'https://insights.hanzo.ai' }}
    >
      <YourApp />
    </InsightsProvider>
  )
}

Next.js

npm install @hanzo/insights @hanzo/insights-next

// app/providers.tsx
'use client'
import { InsightsProvider } from '@hanzo/insights-next'

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <InsightsProvider
      apiKey="your-project-api-key"
      options={{ api_host: 'https://insights.hanzo.ai' }}
    >
      {children}
    </InsightsProvider>
  )
}

Node.js (Server-Side)

npm install @hanzo/insights-node

import { Insights } from '@hanzo/insights-node'

const insights = new Insights('your-project-api-key', {
  host: 'https://insights.hanzo.ai',
})

insights.capture({
  distinctId: 'user-123',
  event: 'api_request',
  properties: {
    endpoint: '/v1/chat/completions',
    model: 'zen5-pro',
    latency_ms: 340,
  },
})

// Flush on shutdown
await insights.shutdown()

Go

go get github.com/hanzoai/insights-go

package main

import "github.com/hanzoai/insights-go"

func main() {
    client, _ := insights.NewWithConfig("your-project-api-key", insights.Config{
        Endpoint: "https://insights.hanzo.ai",
    })
    defer client.Close()

    client.Enqueue(insights.Capture{
        DistinctId: "user-123",
        Event:      "api_request",
        Properties: insights.NewProperties().
            Set("endpoint", "/v1/chat/completions").
            Set("model", "zen5-pro"),
    })
}

Python

pip install hanzo-insights

from hanzo_insights import Insights

insights = Insights('your-project-api-key', host='https://insights.hanzo.ai')

insights.capture(
    distinct_id='user-123',
    event='api_request',
    properties={
        'endpoint': '/v1/chat/completions',
        'model': 'zen5-pro',
    }
)

insights.shutdown()

Verify

After initializing the SDK:

Open insights.hanzo.ai → Activity → Live Events
Perform actions in your app
Events appear within seconds

If events don't appear, check:

API key is correct (project-level, not personal)
api_host points to https://insights.hanzo.ai
No ad blockers are blocking the requests (use a proxy for production — see Self-Hosting)

Next Steps

Roll out features gradually with boolean and multivariate flags

Replay user sessions with full privacy controls

Reference for all standard and custom events

Quickstart

On this page