Node.js SDK integration

Integrate the current GetPassive SDK in a Node.js 18+ runtime. The SDK connects to GetPassive over a secure WebSocket, authenticates with your developer API key, and relays approved bandwidth sessions only after your app has handled consent.

Requirements

• Node.js 18 or newer. The current @getpassive/sdk package is server-side JavaScript only.
• npm access to the GetPassive private registry at https://npm.getpassive.io/.
• A developer API key for an approved app in the GetPassive dashboard.
• An app flow that can present the required consent disclosure before starting the SDK.

Step 1: Get your developer API key

Create or open your app in the GetPassive dashboard. The dashboard issues a developer API key for the app. Store it as an environment variable and keep it out of source control.

export GETPASSIVE_DEV_API_KEY="gp_pk_..."

Step 2: Configure .npmrc for npm.getpassive.io

Add a project-level .npmrc file so npm resolves the @getpassive scope from the private registry. Use an environment variable for the registry token.

@getpassive:registry=https://npm.getpassive.io/
//npm.getpassive.io/:_authToken=${GETPASSIVE_NPM_TOKEN}

Ask your GetPassive contact or dashboard administrator for registry access if your install receives a 401 or 404 from the private registry.

Step 3: Install the SDK

npm install @getpassive/sdk

The package is an ES module and includes TypeScript declarations. Its runtime WebSocket dependency is installed automatically.

Step 4: Initialize the client

Start the SDK after your app has shown the required consent disclosure. This quickstart is from the current SDK package.

import { GetPassiveClient } from '@getpassive/sdk';

const client = new GetPassiveClient({
  devApiKey: process.env.GETPASSIVE_DEV_API_KEY,
  onStatus(status) {
    console.log('GetPassive status:', status);
  },
  onError(err) {
    console.error('GetPassive error:', err);
  },
});

await client.start();

process.on('SIGINT', async () => {
  await client.stop();
  process.exit(0);
});

Persist deviceUuid in production

If deviceUuid is not provided, the SDK generates one with crypto.randomUUID(). For production apps, persist a stable UUID across restarts so the same installation keeps a stable identity.

import { readFile, writeFile, mkdir } from 'node:fs/promises';
import { randomUUID } from 'node:crypto';
import path from 'node:path';
import { GetPassiveClient } from '@getpassive/sdk';

async function loadDeviceUuid(dataDir) {
  const file = path.join(dataDir, 'getpassive-device-uuid');
  try {
    return (await readFile(file, 'utf8')).trim();
  } catch {
    const uuid = randomUUID();
    await mkdir(dataDir, { recursive: true });
    await writeFile(file, uuid, 'utf8');
    return uuid;
  }
}

const client = new GetPassiveClient({
  devApiKey: process.env.GETPASSIVE_DEV_API_KEY,
  deviceUuid: await loadDeviceUuid('/var/lib/my-app'),
});

await client.start();

Step 5: Consent handling

GetPassive does not render consent UI inside the Node.js SDK. Your app must disclose the passive bandwidth feature in its Terms and Conditions or consent screen before the SDK starts, and it must provide a clear way to opt out by stopping the client.

• Show the disclosure before the first SDK start.
• Do not start the SDK if the user has opted out.
• Call client.stop() when the user opts out, signs out, or uninstalls your app.
• Submit consent-flow changes for review when required by the compliance policy.

See the full consent model for suggested wording and what the SDK does and does not collect.

Step 6: Verification

During integration, confirm both local SDK status and dashboard-side activity.

1. Run the app with a valid GETPASSIVE_DEV_API_KEY.
2. Watch onStatus for connecting followed by connected.
3. Check onError output for invalid keys, registry mismatch, or network failures.
4. Open your app in the dashboard and verify that the device appears as recently connected.

const client = new GetPassiveClient({
  devApiKey: process.env.GETPASSIVE_DEV_API_KEY,
  onStatus: (status) => console.log(`[getpassive] ${status}`),
  onError: (error) => console.error('[getpassive]', error),
});

The SDK maintains a secure WebSocket connection to wss://sdk.getpassive.io. If the connection drops, it reconnects with exponential backoff from 1 second up to 30 seconds.

Step 7: Update the SDK

Update the package with npm, then restart your app in a test environment and confirm the normal connected status before shipping.

npm update @getpassive/sdk
npm ls @getpassive/sdk

SDK version upgrades alone do not require app re-review unless you also change consent wording, consent placement, opt-out behavior, or where the SDK starts in your app flow.

Last updated June 29, 2026