Support for Mixpanel Feature Flags

The SDK can now be used to load and evaluate Mixpanel Feature Flags (see https://docs.mixpanel.com/docs/featureflags). It supports two modes of operation, remote evaluation and local evaluation.

Remote Evaluation

const mixpanel = Mixpanel.init(`<YOUR_TOKEN>`, {
  remote_flags_config: {
    // optional configuration
    request_timeout_in_seconds: 5,
  },
});

// or to enable remote evaluation with no custom configuration:
const mixpanel = Mixpanel.init(`<YOUR_TOKEN>`, {
  remote_flags_config: {},
});

// A network call is made to fetch the assigned variant for a user
const variantValue = await mixpanel.remote_flags.getVariantValue(`<YOUR_FLAG_KEY>`, `<FALLBACK_VARIANT>`, {
  distinct_id : `<USER DISTINCT ID>`,
});

Local Evaluation

const mixpanel = Mixpanel.init(`YOUR_PROJECT_TOKEN`, {
  local_flags_config: {
    enable_polling: true,
    polling_interval_in_seconds: 60,
  },
});

// or to enable local evaluation with no custom configuration:
const mixpanel = Mixpanel.init(`<YOUR_TOKEN>`, {
  local_flags_config: {},
});

// Polls the endpoint for flag definitions 
mixpanel.local_flags.startPollingForDefinitions();

// User is quickly assigned to a variant based on polled flag definitions
const variantValue = mixpanel.local_flags.getVariantValue(`<YOUR_FLAG_KEY>`, `<FALLBACK_VARIANT>`, {
  distinct_id : `<USER_DISTINCT_ID`,
});

Further Node.js-specific Feature Flags documentation is available at https://docs.mixpanel.com/docs/tracking-methods/sdks/nodejs/nodejs-flags.

Custom logger support

The library can now be initialized with a logger option to provide custom logging instead of the default console logging:

const bunyan = require(`bunyan`);
const mixpanel = Mixpanel.init(`<YOUR_TOKEN>`, {debug: true, logger: bunyan});

Any logger which implements the interface at https://github.com/mixpanel/mixpanel-node/blob/7f334f1d3f07e1c7783887b8090211614a26d5bc/lib/mixpanel-node.d.ts#L9-L15 will work:

export interface CustomLogger {
  trace(message?: any, ...optionalParams: any[]): void;
  debug(message?: any, ...optionalParams: any[]): void;
  info(message?: any, ...optionalParams: any[]): void;
  warn(message?: any, ...optionalParams: any[]): void;
  error(message?: any, ...optionalParams: any[]): void;
}

Support has also been dropped for the long-deprecated Mixpanel.Client() initializer.

Default to millisecond-precision timestamps

As of this release, time properties set as Date objects will be sent to the Mixpanel API with millisecond precision (instead of being rounded to the second).

Support for geolocation and library version property

The configuration option geolocate can be used to take advantage of Mixpanel's automatic geolocation properties (converting the source IP address into properties for country/region/city). This is generally useful when the NodeJS SDK is used in a client application, such as an Electron app or IoT device; whereas in a server application (e.g. an Express application server), the IP address will be that of the server rather than the user. To turn on geolocation, initialize the library with geolocate: true:

const mixpanel = Mixpanel.init('<YOUR_TOKEN>', {
  geolocate: true,
});

The SDK also now sends the current library version as a property with every event, like Mixpanel's other SDKs.

Use keepAlive by default for request connections

The library now defaults to using keepAlive (https://nodejs.org/api/http.html#new-agentoptions) so that each request doesn't have to establish a new connection. This should result in better performance and network reliability. If you need to turn this option off, initialize the library with keepAlive: false:

const mixpanel = Mixpanel.init('<YOUR_TOKEN>', {
  keepAlive: false,
});

Support for latitude/longitude in profile operations

Profile update operations set and set_once now support passing latitude/longitude for geolocation (see https://help.mixpanel.com/hc/en-us/articles/115004499343#latitude-and-longitude-based-geolocation). These should be passed in the 'modifiers' object param, e.g.:

mixpanel.people.set('billybob', {
  plan: 'premium',
  games_played: 1,
}, {
  $latitude: 40.7127753,
  $longitude: -74.0059728,
});

Event operations like track() already supported latitude/longitude as regular event properties.

API Secret support for imports

The supported method for authenticating import() calls (for events more than 5 days old) is now via the project's API Secret, passed via the secret config option:

const mixpanel = Mixpanel.init(`<TRACKING TOKEN>`, {secret: `<API SECRET>`});

This will be passed as a HTTP Basic auth header as described in https://developer.mixpanel.com/reference/importing-old-events. It will only be sent over HTTPS (the default protocol); the library will throw an error rather than send the secret over HTTP in plaintext.

The older API "Key" authentication for import will still work, but is now deprecated and may be removed in a future version.

Support for Groups API

This release adds support for Mixpanel Groups, through the mixpanel.groups object, analogous to mixpanel.people. For projects which have groups support enabled, you can send group profile updates via calls such as:

mixpanel.groups.set('company', 'Acme Inc.', {
    'Industry': 'widgets',
    '$name': 'Acme Inc.',
});

mixpanel.groups.remove('company', 'Acme Inc.', {
  'products': 'anvil',
  'customer segments': 'coyotes'
});

mixpanel.groups.delete_group('company', 'Acme Inc.');

// etc

Support for configurable API path

Configure when initializing the instance with the path option:

const mixpanel = Mixpanel.init(`YOUR TOKEN`, {
  host: `sweet-corporate-proxy:6000`,
  path: `/mixpanel`,
});

In the above example, tracking requests will go to https://sweet-corporate-proxy:6000/mixpanel/track.

Dropped Node.js 4 support

v0.10.0

0.10.0