mixpanel-node

Context properties are passed directly to Mixpanel for targeting and bucketing. You can set context globally or per-evaluation.

Note: targetingKey is treated as a standard context property and is not used as a special bucketing key by this provider. Mixpanel's server-side configuration determines which properties are used for targeting.

Global Context

await OpenFeature.setProviderAndWait(provider);
OpenFeature.setContext({ environment: "production" });

Per-evaluation Context

Per-evaluation context is merged with and overrides global context.

const value = await client.getBooleanValue("premium-feature", false, {
  distinct_id: "user-123",
  email: "user@example.com",
  plan: "premium",
  beta_tester: true,
});

// Global
OpenFeature.setContext({ environment: "production" });

// Per-evaluation
const value = await client.getBooleanValue("flag", false, { distinct_id: "123", plan: "premium" });

After registering the provider with OpenFeature.setProviderAndWait(provider), use the OpenFeature client to evaluate flags.

Mapping Mixpanel Flag Types to OpenFeature Methods

Example Usage

import { OpenFeature } from "@openfeature/server-sdk";
import { MixpanelProvider } from "@mixpanel/openfeature-server-provider";

const provider = MixpanelProvider.createLocal("YOUR_PROJECT_TOKEN");
await OpenFeature.setProviderAndWait(provider);

const client = OpenFeature.getClient();
const context = { distinct_id: "user-123" };

// Feature Gate
const isFeatureOn = await client.getBooleanValue("new-checkout", false, context);

// Experiment (String)
const buttonColor = await client.getStringValue("button-color-test", "blue", context);

// Experiment (Number)
const maxItems = await client.getNumberValue("max-items", 10, context);

// Dynamic Config (JSON)
const featureConfig = await client.getObjectValue("homepage-layout", {}, context);

The MixpanelProvider can be initialized using three different strategies depending on your latency and real-time requirements:

1. Local Evaluation (Recommended)

Evaluates flags locally using cached definitions polled from Mixpanel. This minimizes latency for server-side applications.

const provider = MixpanelProvider.createLocal("YOUR_PROJECT_TOKEN");

2. Remote Evaluation

Makes a network request to Mixpanel for every evaluation. Use this if you need real-time flag values and can tolerate network latency.

const provider = MixpanelProvider.createRemote("YOUR_PROJECT_TOKEN");

3. Using an Existing Mixpanel Instance

If you already have a configured mixpanel instance, you can wrap its existing flags provider. Note that in this mode, provider.mixpanel will be undefined.

import Mixpanel from "mixpanel";

const mixpanel = Mixpanel.init("YOUR_PROJECT_TOKEN", {
  local_flags_config: {},
});
const localFlags = mixpanel.local_flags!;
localFlags.startPollingForDefinitions();

const provider = new MixpanelProvider(localFlags);

// Local Evaluation
const provider = MixpanelProvider.createLocal("YOUR_PROJECT_TOKEN");

// Remote Evaluation
const provider = MixpanelProvider.createRemote("YOUR_PROJECT_TOKEN");

// Existing Instance
const provider = new MixpanelProvider(localFlags);

Service accounts are the preferred method for server-to-server integrations and provide enhanced security.

When to use Service Accounts:

• Importing historical events: Required for events older than 5 days via the .import() endpoint.
• Server-side feature flags: Required for evaluating feature flags with authentication.

When Service Accounts are NOT needed:

• Regular event tracking: .track() only requires the project token.
• People analytics: .people.set(), .people.increment(), etc., do not require service account authentication.

Note: API secrets are DEPRECATED and should be migrated to Service Accounts.

const { ServiceAccountCredentials } = Mixpanel;

const credentials = new ServiceAccountCredentials(
  "YOUR_SERVICE_ACCOUNT_USERNAME",
  "YOUR_SERVICE_ACCOUNT_SECRET",
  "YOUR_PROJECT_ID",
);

// Initialize with credentials
var mixpanel = Mixpanel.init("<YOUR_TOKEN>", { credentials });

To use Mixpanel flags with the OpenFeature SDK, you must first create a provider instance using either createLocal or createRemote, and then call initialize().

• createLocal(token, config): Used for local flag evaluation. It initializes a Mixpanel instance and starts polling for flag definitions.
• createRemote(token, config): Used for remote flag evaluation (server-side).
• initialize(context): Captures a global evaluation context and awaits the readiness of the flags provider (e.g., waiting for the first successful fetch of definitions in local mode).

import { MixpanelProvider } from 'mixpanel-node/openfeature-server-provider';

// For local evaluation
const provider = MixpanelProvider.createLocal('YOUR_MIXPANEL_TOKEN', { /* LocalFlagsConfig */ });

// Or for remote evaluation
// const provider = MixpanelProvider.createRemote('YOUR_MIXPANEL_TOKEN', { /* RemoteFlagsConfig */ });

await provider.initialize({ user_id: '123' });

Record user actions by calling .track(event_name, properties).

Important Mental Model: Unlike client-side libraries, mixpanel-node is stateless and does not use identify(). You must pass the distinct_id within the properties object of every tracking call to associate the event with a user.

Features:

• Properties: Pass an object of custom properties.
• Geolocation: Pass an ip property to get automatic geolocation info.
• Timestamps: Pass a time property (up to 5 days old). For older events, use .import().
• Batching: Use .track_batch([...]) to send multiple events in a single request for efficiency.
• Callbacks: All functions accept an optional callback as the last argument to handle errors.

// Basic tracking
mixpanel.track("my event", {
  distinct_id: "some unique client id",
  as: "many",
  properties: "as",
  you: "want",
});

// Tracking with IP for geolocation
mixpanel.track("my event", { ip: "127.0.0.1" });

// Tracking with a specific timestamp
mixpanel.track("timed event", { time: new Date() });

// Batch tracking
mixpanel.track_batch([
  {
    event: "recent event",
    properties: {
      time: new Date(),
      distinct_id: "billybob",
      gender: "male",
    },
  },
  {
    event: "another recent event",
    properties: {
      distinct_id: "billybob",
      color: "red",
    },
  },
]);

// Using a callback
mixpanel.track("test", function (err) {
  if (err) throw err;
});