JSPM

  • Created
  • Published
  • Downloads 101
  • Score
    100M100P100Q81942F
  • License MIT

Lightweight TypeScript SDK for sending analytics events and managing remote configurations via Grain's REST API

Package Exports

  • @grainql/analytics-web
  • @grainql/analytics-web/react

Readme


Grain

Grain Analytics Web SDK

Lightweight TypeScript SDK for event tracking and remote configuration via Grain.
Works in browsers, Node.js, and any JavaScript runtime.

npm version License


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