@jakobinn/aj-client-sdk

A lightweight client for sending analytics events with batching and graceful flushing. Works in browsers, Node.js, and React Native. Types included.

⚠️ Breaking Change in v2.0.0: API key authentication has been updated to use Authorization headers instead of query parameters for improved security. See CHANGELOG.md for migration details.

Install

npm install @jakobinn/aj-client-sdk
# or
pnpm add @jakobinn/aj-client-sdk
# or
yarn add @jakobinn/aj-client-sdk

Quick start

import { AnalyticsJJClient } from '@jakobinn/aj-client-sdk';

const analytics = new AnalyticsJJClient({
  apiKey: 'YOUR_SERVER_API_KEY',
  host: 'YOUR_ANALYTICS_HOST_URL',
  refer: true,   // optional (browser-only): auto track ?trc11 and external referrers
  debug: false,  // optional: log request diagnostics
});

analytics.track('SCREEN_VIEW', 'HOME_SCREEN_OPENED', { userId: 'user_123' });
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', { rating: 5, text: 'Great!' });

// Flush immediately if needed
await analytics.flush();

Configuration

• apiKey (string, required): Your server-issued API key.
• host (string, optional): Base URL of your analytics API (e.g., https://your-analytics-domain.com). If omitted in the browser, requests go to the current origin.
• flushInterval (number, optional): Milliseconds to wait after the last event before auto-flush. Default 5000.
• batchSize (number, optional): Number of queued events triggering an immediate flush. Default 20.
• refer (boolean, optional): Enables automatic browser tracking of campaign parameter trc11 and external referrers.
• runtime (string, optional): Constant runtime identifier injected into each event. One of 'server' | 'app' | 'client' | 'browser' | 'react_native' | string.
• setUserTimestamp (boolean, optional): If true, includes ISO timestamp in user_timestamp on every event.
• debug (boolean, optional): If true, logs request/response diagnostics.

Environment auto-detection:

• If you do not pass environment, the client uses process.env.ENVIRONMENT when available (production | development | test).

Automatic campaign & referrer tracking (browser)

Runs once at client initialization only when refer: true.

• Tracks CLICKTHROUGH → CAMPAIGN_CLICK if the URL contains ?trc11=... (once per session) and removes the param from the URL.
• Otherwise tracks CLICKTHROUGH → REFERRAL_VISIT if there is an external document.referrer (once per session).

Feedback events

// Simple thumbs up/down
analytics.feedback('POSTER_LIKED', 'POSTER_WIDGET', { vote: 'GOOD' });

// Rating with text
analytics.feedback('FEATURE_RATING', 'FEATURE_MODAL', { rating: 4, text: 'Easy to use' });

// Bug report
analytics.feedback('BUG_REPORTED', 'ERROR_SCREEN', {
  kind: 'BUG', severity: 'HIGH', text: 'Crash when uploading large files', contactOk: true, email: '[email protected]'
});

Feedback payload is attached to jsonData with schema feedback.v1 and includes fields like kind, vote, rating, text, tags, severity, context, etc.

API

new AnalyticsJJClient(config: {
  apiKey: string;
  host?: string;
  flushInterval?: number;
  batchSize?: number;
  refer?: boolean;
  runtime?: 'server' | 'app' | 'client' | 'browser' | 'react_native' | string;
  setUserTimestamp?: boolean;
  debug?: boolean;
});

track(eventType: AnalyticsEventType, eventName: string, properties?: TrackProperties): void;
feedback(eventName: string, source: string, data?: Partial<FeedbackDataV1>, properties?: TrackProperties): void;
flush(): Promise<void>;

Key types:

• AnalyticsEventType: CLICKTHROUGH | INTERACTION | SUBMIT | SEARCH | SCREEN_VIEW | SYSTEM | ERROR | SESSION | AUTH | CONVERSION | FEEDBACK | CUSTOM
• TrackProperties highlights: userId, email, groupId, subscriptionStatus, isSubscribed, data, jsonData, environment, event_name_detailed, runtime, user_timestamp.

Auth and transport

• API Key Authentication: Uses Authorization: Bearer <apiKey> header for all requests
• Transport: POST /api/v1/track with JSON body { events: [...] }
• Security: API keys are never exposed in URLs or server logs
• Standards: Follows HTTP authentication conventions

Troubleshooting

• 400 from server: enable debug: true to log status and body preview; verify host, apiKey, and that your server accepts the auth and payload formats above.
• React Native networking:
  • Android emulator → host machine: use http://10.0.2.2:<port> instead of http://localhost:<port>
  • iOS simulator: http://localhost:<port> works. Physical devices should use your machine's LAN IP.