For browser analytics with heatmaps, snapshots, and consent management, use @grainql/tag instead. This SDK is the right choice when you need remote configuration or need to send events from servers and non-browser environments.

Installation

npm install @grainql/analytics-web

Quick Start

Server-Side / Node.js

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({
  tenantId: 'your-tenant-id',
  authStrategy: 'SERVER_SIDE',
  secretKey: 'your-secret-key',
});

// Track server-side events
grain.track('order_completed', {
  order_id: 'ORD-123',
  total: 149.99,
  currency: 'USD',
});

// Track with an explicit user ID
grain.trackForUser('user-456', 'subscription_renewed', {
  plan: 'pro',
  period: 'annual',
});

// Flush before process exit
await grain.flush();

Remote Configuration

import { createGrainAnalytics } from '@grainql/analytics-web';

const grain = createGrainAnalytics({ tenantId: 'your-tenant-id' });

// Fetch remote config from Grain dashboard
await grain.fetchConfig();

// Read values
const heroText = grain.getConfig('hero_text');
const featureEnabled = grain.getConfig('new_feature') === 'true';

// Get all configs with fallback defaults
const allConfigs = grain.getAllConfigs();

// Listen for config changes
grain.onConfigChange((configs) => {
  console.log('Config updated:', configs);
});

React (Remote Config Hooks)

import { GrainProvider, useConfig, useTrack } from '@grainql/analytics-web/react';

function App() {
  return (
    <GrainProvider config={{ tenantId: 'your-tenant-id' }}>
      <HomePage />
    </GrainProvider>
  );
}

function HomePage() {
  const { value: heroText } = useConfig('hero_text');
  const track = useTrack();

  return (
    <div>
      <h1>{heroText || 'Welcome!'}</h1>
      <button onClick={() => track('cta_clicked')}>Get Started</button>
    </div>
  );
}

Configuration

createGrainAnalytics({
  tenantId: 'your-tenant-id',             // Required
  apiUrl: 'https://clientapis.grainql.com', // Default
  debug: false,                            // Enable debug logging
  // Authentication
  authStrategy: 'NONE',                   // 'NONE' | 'SERVER_SIDE' | 'JWT'
  secretKey: undefined,                    // For SERVER_SIDE auth
  authProvider: undefined,                 // For JWT auth
  // Batching
  batchSize: 50,                           // Events per batch
  flushInterval: 5000,                     // Flush interval in ms
  retryAttempts: 3,                        // Retry attempts on failure
  // Remote Config
  defaultConfigurations: {},               // Fallback values
  configRefreshInterval: 300000,           // Auto-refresh (5 min default)
  enableConfigCache: true,                 // Cache configs locally
  // Privacy
  consentMode: 'cookieless',              // 'cookieless' | 'gdpr-strict' | 'gdpr-opt-out'
});

API Reference

Event Tracking

grain.track(eventName, properties?)                // Track with current user
grain.trackForUser(userId, eventName, properties?) // Track with explicit user
grain.flush()                                      // Flush pending events

Identity

grain.setUserId(userId)              // Set user identity
grain.getUserId()                    // Get current user ID
grain.getDeviceId()                  // Get device ID
grain.getSessionId()                 // Get session ID

Remote Configuration

grain.fetchConfig(options?)          // Fetch configs from API
grain.getConfig(key)                 // Get a single config value
grain.getAllConfigs()                 // Get all configs with defaults
grain.onConfigChange(callback)       // Listen for config changes

Consent

grain.grantConsent(categories?)      // Grant consent
grain.revokeConsent()                // Revoke consent
grain.hasConsent()                   // Check consent status

Lifecycle

grain.destroy()                      // Flush and cleanup

When to Use Which SDK

| Use Case | SDK | |----------|-----| | Browser analytics, heatmaps, snapshots | @grainql/tag | | Script tag delivery (Cloudflare Workers) | @grainql/tag | | Remote configuration | @grainql/analytics-web | | Server-side event tracking (Node.js) | @grainql/analytics-web | | React config hooks (useConfig) | @grainql/analytics-web/react | | Non-browser runtimes | @grainql/analytics-web |

License

MIT