# Setup Mixpanel

Prefer using the @workleap/telemetry umbrella package over this standalone library.

While we recommend using the @workleap/telemetry umbrella package, Workleap's LogRocket instrumentation can also be used as a standalone @worleap/mixpanel package.

To set it up, follow these steps 👇

# Install the packages

First, open a terminal at the root of the application and install the following packages:

pnpm add @workleap/mixpanel

# Initialize Mixpanel

Then, initialize Mixpanel using the initializeMixpanel function:

import { initializeMixpanel, MixpanelProvider, createTelemetryContext } from "@workleap/mixpanel/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

const client = initializeMixpanel("wlp", "development", {
    telemetryContext: createTelemetryContext()
});

const root = createRoot(document.getElementById("root")!);

root.render(
    <StrictMode>
        <MixpanelProvider client={client}>
            <App />
        </MixpanelProvider>
    </StrictMode>
);

# Create a track function

Then create a track function using the useTrackingFunction hook if the host application is in React:

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction();

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Track an event

Finally, using the retrieved track function to send a telemetry event:

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction();

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Track a link

Link clicks requires to keep the page alive while the tracking request is being processed. To do so, set the keepAlive option of the track function:

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction();

track("LinkClicked", { "Trigger": "ChangePlan", "Location": "Header" }, {
    keepAlive: true
});

# Set custom user properties

Most applications need to set custom properties about the current user environment on all events. To help with that, MixpanelClient expose the setGlobalEventProperties method:

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

client.setGlobalEventProperties({
    "User Id": "123" 
})

Now, every event recorded after the execution of setGlobalEventProperties will include the custom property User Id.

# Integrate with LogRocket

Starting with version 3.0, attaching LogRocket session replays to Mixpanel events requires providing a LogRocketInstrumentationClient to the registration function:

import { initializeMixpanel, MixpanelProvider, createTelemetryContext } from "@workleap/mixpanel/react";
import { registerLogRocketInstrumentation } from "@workleap/logrocket/react";
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

const logRocketInstrumentationClient = registerLogRocketInstrumentation("my-app-id");

const mixpanelClient = initializeMixpanel("wlp", "development", {
    telemetryContext: createTelemetryContext(),
    logRocketInstrumentationClient
});

const root = createRoot(document.getElementById("root")!);

root.render(
    <StrictMode>
        <MixpanelProvider client={mixpanelClient}>
            <App />
        </MixpanelProvider>
    </StrictMode>
);

# Try it 🚀

Start the application in a development environment using the dev script. Render a page, then navigate to your Mixpanel instance. Go to "Events" page. If you are tracking events, you should see a new event appear.

You can try filtering the event list using different properties, such as:

User Id

# Troubleshoot issues

If you are experiencing issues with this guide:

Set the verbose predefined option to true.
Open the DevTools console and look for logs starting with [mixpanel].
Refer to the sample on GitHub.

# Reference

# initializeMixpanel

Initialize Mixpanel with Workleap's default settings.

const client = initializeMixpanel(productId, envOrTrackingApiBaseUrl, options?: { 
    trackingEndpoint?,
    telemetryContext?,
    logRocketInstrumentationClient?,
    verbose?,
    loggers?
})

# Parameters

productId: The product id.
envOrTrackingApiBaseUrl: The environment to get the navigation url from or a base URL.
options: An optional object literal of options:
- trackingEndpoint: An optional tracking endpoint.
- telemetryContext: A TelemetryContext instance containing the telemetry correlation ids to attach to Honeycomb traces. Starting with version 7.0, if no telemetry context is provided, the correlation ids will not be attached to Honeycomb traces.
- logRocketInstrumentationClient: A LogRocketInstrumentationClient instance to integrate Honeycomb traces with LogRocket session replays. Starting with version 7.0, if no LogRocket instrumentation client is provided, the Honeycomb traces will not integrate with LogRocket session replays.
- verbose: If no loggers are configured, verbose mode will automatically send logs to the console. In some cases, enabling verbose mode also produces additional debug information.
- loggers: An optional array of RootLogger instances.

# Returns

A MixpanelClient instance.

# Environments

Supported environments are:

production
staging
development
local
msw

# Initialize with a predefined environment

Mixpanel can be initialized for any of the following predefined environments:

import { initializeMixpanel } from "@workleap/mixpanel/react";

const client = initializeMixpanel("wlp", "development");

# Initialize with a base url

import { initializeMixpanel } from "@workleap/mixpanel/react";

const client = initializeMixpanel("wlp", "https://my-tracking-api");

# Use a custom tracking endpoint

import { initializeMixpanel } from "@workleap/mixpanel/react";

const client = initializeMixpanel("wlp", "development", {
    trackingEndpoint: "custom/tracking/track"
});

# Initialize with a telemetry context

import { initializeMixpanel, createTelemetryContext } from "@workleap/mixpanel/react";

const telemetryContext = createTelemetryContext();

const client = initializeMixpanel("wlp", "development", {
    telemetryContext
});

# Integrate with LogRocket

import { initializeMixpanel } from "@workleap/mixpanel/react";
import { registerLogRocketInstrumentation } from "@workleap/logrocket/react";

const logRocketInstrumentationClient = registerLogRocketInstrumentation("my-app-id");

const client = initializeMixpanel("wlp", "development", {
    logRocketInstrumentationClient
});

# Verbose mode

import { initializeMixpanel } from "@workleap/mixpanel/react";

const client = initializeMixpanel("wlp", "development", {
    verbose: true
});

# Use loggers

import { initializeMixpanel } from "@workleap/mixpanel/react";
import { LogRocketLogger } from "@workleap/logrocket/react";
import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";

const client = initializeMixpanel("wlp", "development", {
    loggers: [new BrowserConsoleLogger(), new LogRocketLogger({ logLevel: LogLevel.information })]
});

# MixpanelClient

A lightweight client providing access to Mixpanel utilities.

const client = new MixpanelClient(productId, endpoint, superProperties, logger);

# Parameters

productId: The product id.
endpoint: The Mixpanel endpoint URL.
globalProperties: Properties to attach to all events.
logger: A Logger instance.

# Methods

createTrackingFunction(options?: { targetProductId? }): Returns a TrackingFunction function sending POST requests to a dedicated tracking endpoint fully compliant with the Workleap platform tracking API.
setGlobalProperty(key, value): Set a single global property that will be attached to all events.
setGlobalProperties(values): Set one or multiple global properties that will be attached to all events.

# `TrackingFunction`

A TrackingFunction have the following signature: (eventName, properties: {}, options?: { keepAlive }) => Promise<void>.

eventName: The event name.
properties: The event properties.
options: An optional object literal of options:
- keepAlive: Whether or not to keep the connection alive for the tracking request. It is mostly used for tracking links where the user might navigate away before the request is completed.

The body size for keepalive requests is limited to 64 kibibytes.

# Track events

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

const track = client.createTrackingFunction();

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Specify a target product

To track an action targeting another product, use the targetProductId option:

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

const track = client.createTrackingFunction({
    targetProductId: "wov"
});

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Track a link

To track a link click, use the keepAlive option to keep the page alive while the tracking request is being processed:

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

const track = client.createTrackingFunction();

track("LinkClicked", { "Trigger": "ChangePlan", "Location": "Header" }, {
    keepAlive: true
});

# Register global properties

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

client.setGlobalEventProperties({
    "User Id": "123"
});

# NoopMixpanelClient

A fake implementation of NoopMixpanelClient for use in non-standard contexts such as unit tests and Storybook.

import { NoopMixpanelClient } from "@workleap/mixpanel/react";

const client = new NoopMixpanelClient();

# MixpanelProvider

React provider to share a MixpanelClient instance with the application code.

<MixpanelProvider client={client}>
    <App />
</MixpanelProvider>

# Properties

client: A MixpanelClient instance.

# Provide a client instance

import { initializeMixpanel, MixpanelProvider } from "@workleap/mixpanel/react";
import { createRoot } from "react-dom/client";
import { App } from "./App.tsx";

const client = initializeMixpanel("wlp", "development");

const root = createRoot(document.getElementById("root"));

root.render(
    <MixpanelProvider client={client}>
        <App />
    </MixpanelProvider>
);

# Retrieve a client instance

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = initializeMixpanel("wlp", "development");

client.setGlobalEventProperties({
    "User Id": "123"
});

# useMixpanelClient

Retrieve a MixpanelClient instance.

const client = useMixpanelClient(options?: { throwOnUndefined? })

# Parameters

options: An optional object literal of options:
- throwOnUndefined: Whether or not an exception should be thrown if a client instance hasn't been provided.

# Returns

A MixpanelClient instance.

# Usage

import { useMixpanelClient } from "@workleap/mixpanel/react";

const client = useMixpanelClient();

client.setGlobalEventProperties({
    "User Id": "123"
});

# useTrackingFunction

Returns a function sending POST requests to a dedicated tracking endpoint fully compliant with the Workleap platform tracking API.

const track = useTrackingFunction(options?: { targetProductId })

# Parameters

options: An optional object literal of options:
- targetProductId: The product id of the target product. Useful to track an event for another product.

# Returns

A TrackingFunction with the following signature: (eventName, properties: {}, options?: { keepAlive }) => Promise<void>.

eventName: The event name.
properties: The event properties.
options: An optional object literal of options:
- keepAlive: Whether or not to keep the connection alive for the tracking request. It is mostly used for tracking links where the user might navigate away before the request is completed.

The body size for keepalive requests is limited to 64 kibibytes.

# Track events

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction();

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Specify a target product

To track an action targeting another product, use the targetProductId option:

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction({
    targetProductId: "wov"
});

track("ButtonClicked", { "Trigger": "ChangePlan", "Location": "Header" });

# Track a link

To track a link click, use the keepAlive option to keep the page alive while the tracking request is being processed:

import { useTrackingFunction } from "@workleap/mixpanel/react";

const track = useTrackingFunction();

track("LinkClicked", { "Trigger": "ChangePlan", "Location": "Header" }, {
    keepAlive: true
});

# createTelemetryContext

Creates a TelemetryContext instance containing the telemetry correlation ids.

const telemetryContext = createTelemetryContext(options?: { identityCookieExpiration?, identityCookieDomain?, verbose?, loggers? })

# Parameters

options: An optional object literal of options:
- identityCookieExpiration: The expiration date of the wl-identity cookie if the cookie hasn't been already written. The default value is 365 days.
- identityCookieDomain: The domain of the wl-identity cookie if the cookie hasn't been already written. The default value is *.workleap
- verbose: If no loggers are configured, verbose mode will automatically send logs to the console. In some cases, enabling verbose mode also produces additional debug information.
- loggers: An optional array of Logger instances.

# Returns

A TelemetryContext instance.

# Create a telemetry context

import { createTelemetryContext } from "@workleap/mixpanel/react";

const context = createTelemetryContext();

import { createTelemetryContext } from "@workleap/mixpanel/react";

const context = createTelemetryContext({
    identityCookieExpiration: new Date(Date.now() + 14 * 24 * 60 * 60 * 1000);
});

import { createTelemetryContext } from "@workleap/mixpanel/react";

const context = createTelemetryContext({
    identityCookieDomain: ".contso.com";
});

# Verbose mode

import { createTelemetryContext } from "@workleap/mixpanel/react";

const context = createTelemetryContext({
    verbose: true
});

# Loggers

import { createTelemetryContext, LogRocketLogger } from "@workleap/mixpanel/react";
import { BrowserConsoleLogger, LogLevel } from "@workleap/logging";

const context = createTelemetryContext({
    loggers: [new BrowserConsoleLogger(), new LogRocketLogger({ logLevel: LogLevel.information })]
});

# Setup Mixpanel

# Install the packages

# Initialize Mixpanel

# Create a track function

# Track an event

# Track a link

# Set custom user properties

# Integrate with LogRocket

# Try it 🚀

# Troubleshoot issues

# Reference

# initializeMixpanel

# Parameters

# Returns

# Environments

# Initialize with a predefined environment

# Initialize with a base url

# Use a custom tracking endpoint

# Initialize with a telemetry context

# Integrate with LogRocket

# Verbose mode

# Use loggers

# MixpanelClient

# Parameters

# Methods

# TrackingFunction

# Track events

# Specify a target product

# Track a link

# Register global properties

# NoopMixpanelClient

# MixpanelProvider

# Properties

# Provide a client instance

# Retrieve a client instance

# useMixpanelClient

# Parameters

# Returns

# Usage

# useTrackingFunction

# Parameters

# Returns

# Track events

# Specify a target product

# Track a link

# createTelemetryContext

# Parameters

# Returns

# Create a telemetry context

# Set a custom cookie expiration

# Set a custom cookie domain

# Verbose mode

# Loggers

# `TrackingFunction`