Skip to main content

Node Server Integration

Use @drivemetadata-ai/sdk/node for backend events only.

Do not use the browser SDK in server code. Browser analytics depends on DOM, cookies, localStorage, sessionStorage, page lifecycle, and session behavior.

Install​

npm install @drivemetadata-ai/sdk

Create Client​

import { createDmdServerClient } from '@drivemetadata-ai/sdk/node';

const dmd = createDmdServerClient({
  clientId: 'client_xxx',
  workspaceId: 'workspace_xxx',
  appId: 'app_xxx',
  token: process.env.DMD_SERVER_TOKEN!,
  endpoint: 'https://sdk.drivemetadata.com/v2/data-collector',
  timeoutMs: 5000,
  retry: {
    attempts: 3,
    minDelayMs: 250,
    maxDelayMs: 2000
  }
});

Track Event​

await dmd.track({
  userId: 'user_123',
  event: 'Invoice Paid',
  messageId: 'evt_123',
  idempotencyKey: 'invoice_123',
  properties: {
    amount: 500,
    currency: 'USD'
  }
});

Idempotency​

Pass messageId when you already have a unique event ID and idempotencyKey when retrying business events such as orders, invoices, or subscriptions.

await dmd.track({
  userId: 'user_123',
  event: 'Order Completed',
  messageId: 'evt_123',
  idempotencyKey: 'order_123'
});

Batch​

await dmd.batch([
  { type: 'track', payload: { userId: 'user_123', event: 'Order Completed' } },
  { type: 'identify', payload: { userId: 'user_123', traits: { plan: 'pro' } } }
]);

Identify User​

await dmd.identify({
  userId: 'user_123',
  traits: {
    plan: 'enterprise',
    seats: 25
  }
});

Page Event​

await dmd.page({
  userId: 'user_123',
  name: 'Billing Settings',
  properties: {
    source: 'server_render'
  }
});

Alias User​

await dmd.alias({
  previousId: 'anonymous_123',
  userId: 'user_123'
});

Group User​

await dmd.group({
  userId: 'user_123',
  groupId: 'account_456',
  traits: {
    companyName: 'Acme Inc'
  }
});

Runtime Requirements​

The Node SDK requires Node.js 18+ because it uses global fetch. For older runtimes, pass a custom fetch implementation:

const dmd = createDmdServerClient({
  clientId: 'client_xxx',
  workspaceId: 'workspace_xxx',
  appId: 'app_xxx',
  token: process.env.DMD_SERVER_TOKEN!,
  fetch: customFetch
});

Server Key Safety​

Use @drivemetadata-ai/sdk/node only in server runtimes. Never import this entry point from browser bundles, React client components, Angular browser bundles, or Next.js client components.

Store server keys in backend-only environment variables:

const dmd = createDmdServerClient({
  clientId: 'client_xxx',
  workspaceId: 'workspace_xxx',
  appId: 'app_xxx',
  token: process.env.DMD_SERVER_TOKEN!,
  timeoutMs: 3000
});

Reliability​

Use timeoutMs to cap request time and retry to retry transient failures such as 408, 429, and 5xx responses. Timeout timers are cleaned up after each request settles.