Pixels Analytics Node.js SDK

A TypeScript SDK for batching and sending analytics events to the Pixels event tracking API, with built-in retry, batching, and graceful shutdown support.

Features

- Batching: Events are queued and sent in batches (default: 100, configurable).
- Automatic Flushing: Events are sent every 5 seconds or when the batch size is reached.
- Exponential Backoff: Retries failed requests with exponential backoff (default: 3 retries).
- Graceful Shutdown: Flushes the queue on process exit or termination signals.
- Strong Typing: TypeScript types for all supported event payloads.
- Supports Test and Live Environments.
- Native fetch: Requires Node.js 18+ (uses global fetch, no axios dependency).

Installation

``bash
npm install @pixels-online/pixels-analytics-node-sdk
`

Usage

`typescript
import PixelsAnalytics from '@pixels-online/pixels-analytics-node-sdk';

const analytics = new PixelsAnalytics({
apiKey: 'YOUR_API_KEY',
clientId: 'YOUR_CLIENT_ID',
env: 'test', // or 'live'
});

// Track a sign-in event
analytics.signIn('playerId123', {
platform: 'email',
platform_identifier: 'user@example.com',
});

// Track a custom event (snake_case event name is enforced)
analytics.custom('custom_event', 'playerId123', { foo: 'bar' });
`

Event Tracking Methods

- gainAchievement(playerId, payload, timestamp?)
- loseAchievement(playerId, payload, timestamp?)
- referUser(payload, timestamp?)
- addTags(payload, timestamp?)
- removeTags(payload, timestamp?)
- signIn(playerId, payload, timestamp?)
- signUp(playerId, payload, timestamp?)
- trustScore(playerId, payload, timestamp?)
- identifierLink(playerId, payload, timestamp?)
- gainMembership(playerId, payload, timestamp?)
- renewMembership(playerId, payload, timestamp?)
- loseMembership(playerId, payload, timestamp?)
- spendCurrency(playerId, payload, timestamp?)
- earnCurrency(playerId, payload, timestamp?)
- withdrawCurrency(playerId, payload, timestamp?)
- depositCurrency(playerId, payload, timestamp?)
- gainItem(playerId, payload, timestamp?)
- gainManyItems(playerId, payload, timestamp?)
- loseItem(playerId, payload, timestamp?)
- loseManyItems(playerId, payload, timestamp?)
- playerToPlayerTrade(payload, timestamp?)
- funnelStart(playerId, payload, timestamp?)
- funnelProgression(playerId, payload, timestamp?)
- funnelEnd(playerId, payload, timestamp?)
- questStart(playerId, payload, timestamp?)
- questProgression(playerId, payload, timestamp?)
- questEnd(playerId, payload, timestamp?)
- levelUp(playerId, payload, timestamp?)
- custom(eventName, playerId, payload, timestamp?) — Track a custom event (eventName is always converted to lower snake_case)

Offer Methods

fetchPlayerCampaigns(playerId, options?)
This method refreshes a player's offers and then returns their current list of in-game offers.

claimRewards({kind: 'offer', instanceId, playerId})
This method allows you to claim an offer for a given player. By calling this method, it will mark the offer as "claimed" and then it will return an array of rewards which you will need to handle in your server.

See src/types.ts for detailed payload structures and type definitions.

Configuration Options

Pass an options object to the PixelsAnalytics constructor:

`typescript
{
apiKey: string;
clientId: string;
env: 'test' | 'live';
maxBatchSize?: number; // default 100
flushInterval?: number; // ms, default 5000
maxRetries?: number; // default 3
}
`

Graceful Shutdown

The SDK automatically flushes the event queue on SIGINT, SIGTERM, or process exit.

Requirements

- Node.js 18+ (for native fetch support)
- TypeScript (for type safety, optional for JS usage)

Migration Notes

- v2: Uses native fetch, not axios. No axios dependency required.
- Event name normalization: The generic/custom` method always converts event names to lower snake_case.

License

AGPLv3