Hanzo
PlatformInsights

SDKs

Client libraries for Hanzo Insights across all major platforms.

Insights SDKs

Hanzo Insights provides 13 official SDKs covering browser, server, and mobile platforms. All SDKs send events to insights.hanzo.ai and support feature flag evaluation.

Browser SDK

The core @hanzo/insights package provides autocapture, pageviews, session recording, feature flags, and custom event tracking.

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,
  session_recording: { maskAllInputs: true },
})

// Custom event
insights.capture('purchase_completed', {
  order_id: 'ord_123',
  total: 49.99,
  currency: 'USD',
})

// Identify user
insights.identify('user-123', {
  email: 'user@example.com',
  plan: 'enterprise',
})

// Group analytics
insights.group('organization', 'org-acme', {
  name: 'Acme Corp',
  plan: 'enterprise',
})

// Feature flag
if (insights.isFeatureEnabled('new-checkout')) {
  renderNewCheckout()
}

// Super properties (included with every event)
insights.register({
  app_version: '2.4.1',
  environment: 'production',
})

// Reset on logout
insights.reset()

Configuration Options

OptionTypeDefaultDescription
api_hoststringhttps://insights.hanzo.aiServer URL
autocapturebooleantrueAuto-capture clicks, forms, page changes
capture_pageviewbooleantrueTrack $pageview events
capture_pageleavebooleantrueTrack $pageleave events
session_recordingobject{}Session recording config
persistencestringlocalStorage+cookieIdentity storage method
cross_subdomain_cookiebooleantrueShare identity across subdomains
bootstrapobjectPre-load feature flags and distinct ID
loadedfunctionCallback after initialization

React SDK

npm install @hanzo/insights @hanzo/insights-react
import {
  InsightsProvider,
  useInsights,
  useFeatureFlag,
  useFeatureFlagPayload,
  useActiveFeatureFlags,
} from '@hanzo/insights-react'

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

// Hooks
function Dashboard() {
  const insights = useInsights()
  const showNewUI = useFeatureFlag('new-dashboard')
  const config = useFeatureFlagPayload('dashboard-config')
  const activeFlags = useActiveFeatureFlags()

  const handleClick = () => {
    insights.capture('button_clicked', { button: 'upgrade' })
  }

  return showNewUI ? <NewDashboard config={config} /> : <LegacyDashboard />
}

Next.js SDK

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

Supports both App Router and Pages Router with automatic page view tracking.

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <InsightsProvider
      apiKey={process.env.NEXT_PUBLIC_INSIGHTS_KEY!}
      options={{ api_host: 'https://insights.hanzo.ai' }}
    >
      {children}
    </InsightsProvider>
  )
}
// Pages Router: pages/_app.tsx
import { insightsNextPageviewTracker } from '@hanzo/insights-next'

function MyApp({ Component, pageProps }) {
  insightsNextPageviewTracker()
  return <Component {...pageProps} />
}

Node.js SDK

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

const insights = new Insights('your-project-api-key', {
  host: 'https://insights.hanzo.ai',
  flushAt: 20,        // Events per batch
  flushInterval: 10000, // Flush interval (ms)
})

// Capture event
insights.capture({
  distinctId: 'user-123',
  event: 'inference_completed',
  properties: {
    model: 'zen4-pro',
    tokens: 1500,
    latency_ms: 340,
  },
})

// Identify user
insights.identify({
  distinctId: 'user-123',
  properties: { email: 'user@example.com', plan: 'pro' },
})

// Evaluate feature flags server-side
const enabled = await insights.isFeatureEnabled('new-api', 'user-123')

// Get all flags for a user
const flags = await insights.getAllFlags('user-123')

// Graceful shutdown
await insights.shutdown()

Go SDK

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()

    // Capture
    client.Enqueue(insights.Capture{
        DistinctId: "user-123",
        Event:      "api_request",
        Properties: insights.NewProperties().
            Set("model", "zen4-pro").
            Set("tokens", 1500),
    })

    // Identify
    client.Enqueue(insights.Identify{
        DistinctId: "user-123",
        Properties: insights.NewProperties().
            Set("email", "user@example.com").
            Set("plan", "pro"),
    })

    // Feature flags
    enabled, _ := client.IsFeatureEnabled(
        insights.FeatureFlagPayload{
            Key:        "new-api",
            DistinctId: "user-123",
        },
    )
}

Python SDK

pip install hanzo-insights
from hanzo_insights import Insights

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

# Capture
insights.capture('user-123', 'inference_completed', {
    'model': 'zen4-pro',
    'tokens': 1500,
})

# Identify
insights.identify('user-123', {
    'email': 'user@example.com',
    'plan': 'pro',
})

# Feature flags
if insights.feature_enabled('new-api', 'user-123'):
    use_new_api()

# All flags
flags = insights.get_all_flags('user-123')

insights.shutdown()

Mobile SDKs

React Native

npm install @hanzo/insights-react-native
import Insights from '@hanzo/insights-react-native'

await Insights.setup('your-project-api-key', {
  host: 'https://insights.hanzo.ai',
  captureApplicationLifecycleEvents: true,
  captureDeepLinks: true,
})

Insights.capture('screen_viewed', { screen: 'home' })

iOS (Swift)

import InsightsSDK

let config = InsightsConfig(apiKey: "your-project-api-key")
config.host = "https://insights.hanzo.ai"
InsightsSDK.shared.setup(config)

InsightsSDK.shared.capture("screen_viewed", properties: ["screen": "home"])

Android (Kotlin)

import ai.hanzo.insights.Insights

val insights = Insights.with(context) {
    apiKey = "your-project-api-key"
    host = "https://insights.hanzo.ai"
}

insights.capture("screen_viewed", mapOf("screen" to "home"))

Flutter

import 'package:hanzo_insights/hanzo_insights.dart';

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

Insights().capture(eventName: 'screen_viewed', properties: {'screen': 'home'});

API Reference

All SDKs communicate with the Insights HTTP API:

MethodEndpointDescription
POST/captureIngest events (batch supported)
POST/decideEvaluate feature flags for a user
POST/batchBatch event ingestion
GET/api/feature_flagGet feature flag definitions
# Direct API call
curl -X POST https://insights.hanzo.ai/capture \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "your-project-api-key",
    "event": "api_request",
    "distinct_id": "user-123",
    "properties": {
      "model": "zen4-pro",
      "tokens": 1500
    }
  }'

How is this guide?

Last updated on

On this page