Server SDK - RetainPixel Docs

Installation

bash

npm install @retainpixel/sdk-node

Configuration

javascript

import { RetainPixel } from '@retainpixel/sdk-node';

const rp = new RetainPixel({
  apiKey: 'rpx_live_YOUR_KEY_HERE',   // Required. Your server API key
  secret: 'YOUR_HMAC_SECRET',         // Optional. For HMAC event signing
});

Option	Type	Description
apiKey	string	Required. Your server-side API key.
secret	string	Optional. HMAC secret for event integrity signing.

Core Methods

rp.track(event)

Send a single track event from your server.

javascript

await rp.track({
  userId: 'user-123',
  event: 'subscription_renewed',
  properties: {
    plan: 'pro',
    mrr: 49.99,
  },
});

rp.identify(payload)

Update user traits from your server.

javascript

await rp.identify({
  userId: 'user-123',
  traits: {
    email: 'user@example.com',
    plan: 'enterprise',
    team_size: 12,
  },
});

rp.group(payload)

Associate a user with a group.

javascript

await rp.group({
  userId: 'user-123',
  groupId: 'company-456',
  traits: {
    name: 'Acme Corp',
    industry: 'SaaS',
  },
});

rp.batch(events)

Send multiple events in a single request for efficiency.

javascript

await rp.batch([
  {
    type: 'track',
    userId: 'user-123',
    event: 'feature_used',
    properties: { feature: 'export' },
  },
  {
    type: 'track',
    userId: 'user-456',
    event: 'feature_used',
    properties: { feature: 'import' },
  },
]);

HMAC Signing

When a secret is configured, the SDK automatically signs every event with an HMAC-SHA256 signature. The ingest endpoint verifies this signature using timing-safe comparison to prevent replay and tampering attacks.

javascript

// Signing happens automatically when secret is provided
const rp = new RetainPixel({
  apiKey: 'rpx_live_YOUR_KEY_HERE',
  secret: process.env.RETAINPIXEL_HMAC_SECRET,
});

// Every event sent through this client includes an integrity_signature
await rp.track({
  userId: 'user-123',
  event: 'payment_completed',
  properties: { amount: 99.99 },
});
// -> Includes header: X-RP-Signature: sha256=<hmac>

The signature covers the full event payload, preventing modification in transit. Server-side events sent with HMAC verification are marked as high-trust in the event store.

Error Handling

All methods return promises. Handle errors with try/catch:

javascript

try {
  await rp.track({
    userId: 'user-123',
    event: 'order_placed',
    properties: { total: 149.99 },
  });
} catch (error) {
  console.error('RetainPixel tracking failed:', error);
  // Events are not retried automatically on the server SDK.
  // Implement your own retry logic if needed.
}