@slnka/compat-segment

Drop-in replacement for @segment/analytics-next -- sovereign analytics for LinkSouverain.ma.

CNDP compliant by default (Law 09-08).

Quick Start

npm install @slnka/compat-segment

Replace your Segment import:

// Before
import Analytics from '@segment/analytics-next';
const analytics = new Analytics({ writeKey: 'SEGMENT_KEY' });

// After
import Analytics from '@slnka/compat-segment';
const analytics = new Analytics({
  writeKey: 'lsk_live_YOUR_KEY',
  apiHost: 'https://api.slnk.ma',
});

All existing tracking calls work without changes:

analytics.track('purchase_completed', { amount: 49.99 });
analytics.identify('user_123', { email: '[email protected]' });
analytics.page('Home');
analytics.group('company_abc', { plan: 'enterprise' });

Dual-Write Mode

Send events to both SLNK and Segment during migration:

const analytics = new Analytics({
  writeKey: 'lsk_live_YOUR_KEY',
  apiHost: 'https://api.slnk.ma',
  dualWrite: true,
  segmentWriteKey: 'SEGMENT_KEY',
});

CNDP Compliance

Tracking requires explicit consent in CNDP mode (default):

// After user grants consent
analytics.optIn();

// Events are now tracked
analytics.track('page_viewed');

// Revoke consent
analytics.optOut();

API Reference

Constructor

new Analytics(config: AnalyticsConfig)

| Option | Type | Default | Description | |--------|------|---------|-------------| | writeKey | string | Required | SLNK API key | | dualWrite | boolean | false | Send to both SLNK and Segment | | segmentWriteKey | string | - | Segment key for dual-write | | apiHost | string | Required | SLNK API base URL (e.g., https://api.slnk.ma) | | workspaceId | string | - | SLNK workspace ID | | flushInterval | number | 5000 | Flush interval in ms | | flushSize | number | 10 | Max buffer before auto-flush | | cndpCompliant | boolean | true | Require consent | | debug | boolean | false | Debug logging |

Methods

| Method | Description | |--------|-------------| | track(event, properties?, options?) | Track a custom event | | identify(userId, traits?, options?) | Identify a user | | group(groupId, traits?, options?) | Associate user with group | | page(name?, properties?, options?) | Track a page view | | screen(name?, properties?, options?) | Track a screen view | | alias(userId, previousId?) | Create an alias | | reset() | Reset identity and flush | | ready(callback) | Called when SDK is ready | | on(event, callback) | Listen for events | | optIn() | Grant tracking consent | | optOut() | Revoke tracking consent | | flush() | Manually flush events |

Migration Guide

See docs/MIGRATION-SEGMENT.md for a complete step-by-step migration guide.

License

MIT