Grain Analytics Web SDK

A lightweight, dependency-free TypeScript SDK for privacy-first analytics and remote configuration management.


🆕 What's New in v3.0

🔒 Privacy-First by Default:
- ✅ Cookieless - No tracking cookies, daily rotating IDs
- ✅ GDPR Compliant - Cookieless mode requires no consent
- ✅ No IP Storage - GeoIP data only (country, region, city)
- ✅ Query Params Stripped - Privacy-first URL tracking
- ✅ Three Consent Modes - Choose your privacy level

🚨 Breaking Changes: This is a major version with breaking changes. See BREAKING_CHANGES.md and MIGRATION_GUIDE_V2.md.

Features

- 🔒 Privacy-First - Cookieless by default, GDPR compliant
- 🚀 Zero dependencies - ~7KB gzipped
- 📦 Automatic batching - Efficient event delivery
- 🔄 Retry logic - Reliable with exponential backoff
- 🎯 TypeScript first - Full type safety
- ⚙️ Remote Config - Dynamic app control without deployments
- ⚛️ React Hooks - Seamless React integration
- 📱 Cross-platform - Browser, Node.js, React Native

Installation

$3

``bash
npm install @grainql/analytics-web
`

$3

`html




`

Quick Start

$3

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

// Cookieless by default (no consent needed)
const grain = createGrainAnalytics({
tenantId: 'your-tenant-id',
consentMode: 'cookieless', // Default: daily rotating IDs
});

// Track events
grain.track('page_viewed', { page: '/home' });

// Get remote config
const heroText = grain.getConfig('hero_text');
`

For GDPR Strict (with consent management):

`typescript
const grain = createGrainAnalytics({
tenantId: 'your-tenant-id',
consentMode: 'gdpr-strict', // Requires consent for permanent IDs
waitForConsent: true, // Queue events until consent granted
});

// Show consent banner
if (!grain.hasConsent()) {
// Show your consent UI
showConsentBanner({
onAccept: () => grain.grantConsent(['analytics']),
onReject: () => grain.revokeConsent(),
});
}
`

$3

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

function App() {
return (



);
}

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

return (



);
}
`

Documentation

For comprehensive guides, API reference, and examples, visit our documentation:

📚 Full Documentation

$3

- Quick Start Guides - Choose your platform and get started in 5 minutes
- React | Next.js | Vanilla JS | CDN | Node.js
- No-Code Integrations - GTM, Shopify, WordPress
- Event Tracking - Track user actions
- Remote Configuration - Dynamic app control
- React Hooks - React integration
- API Reference - Complete API docs
- Examples - Real-world examples

Key Concepts

$3

Track user actions with automatic batching and retry logic:
`typescript
grain.track('button_clicked', { button: 'signup' });
await grain.trackPurchase({ orderId: '123', total: 99.99 });
`

$3

Control your app dynamically without code deployments:
`typescript
const featureEnabled = grain.getConfig('new_feature');
if (featureEnabled === 'true') {
// Show feature
}
`

$3

Track users across sessions:
`typescript
grain.setUserId('user_123');
await grain.setProperty({ plan: 'premium' });
`

$3

Track user journeys from start to goal to unlock path visualization:

`typescript
// 1. Define meaningful event names for your journey
grain.track('signup_started', { source: 'homepage' });
grain.track('email_entered', { valid: true });
grain.track('password_created', { strength: 'strong' });
grain.track('signup_completed', { method: 'email' });

// 2. In the dashboard, create a Track:
// - Start event: 'signup_started'
// - Goal event: 'signup_completed'
// - The system will automatically visualize all paths between them

// 3. Best practices for Tracks:
// - Use consistent event naming (snake_case recommended)
// - Track intermediate steps (not just start/end)
// - Add properties to segment paths (e.g., source, device_type)
// - Exclude noise: heartbeat events are filtered automatically
``

What you'll see in Tracks:
- Conversion paths: Most common routes users take to reach the goal
- Drop-off paths: Where users abandon the journey
- Hub nodes: Critical events many paths flow through
- Metrics: Conversion rate, time-to-goal, abandonment points

More Examples

Check the examples directory for:
- Vanilla JavaScript usage
- React integration
- Next.js setup
- E-commerce tracking
- Authentication flows

Contributing

We welcome contributions! Please see our contributing guidelines for more details.

License

MIT © Grain Analytics

Support

- Documentation: docs.grainql.com
- Dashboard: grainql.com/dashboard
- Issues: GitHub Issues
- Email: support@grainql.com