Package Exports
- @grainql/analytics-web
- @grainql/analytics-web/react
Readme
Grain Analytics Web SDK
Lightweight TypeScript SDK for event tracking and remote configuration via Grain.
Works in browsers, Node.js, and any JavaScript runtime.
For browser analytics with heatmaps, snapshots, and consent management, use
@grainql/taginstead. 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-webQuick 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 eventsIdentity
grain.setUserId(userId) // Set user identity
grain.getUserId() // Get current user ID
grain.getDeviceId() // Get device ID
grain.getSessionId() // Get session IDRemote 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 changesConsent
grain.grantConsent(categories?) // Grant consent
grain.revokeConsent() // Revoke consent
grain.hasConsent() // Check consent statusLifecycle
grain.destroy() // Flush and cleanupWhen 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 |