mixpanel-utils

Collection of Mixpanel utility functions for easy setup and usage of Mixpanel.

Installation

Install this package using npm install @portxchange/mixpanel-utils.

Usage

Initialisation

First, we need to wrap your application with a Mixpanel provider. To do that, implement the following code, so it's executed before any other Mixpanel code is run:

import React, { useEffect } from "react";
import { MixpanelProvider } from "@portxchange/mixpanel-utils";

export const App = () => (
  <MixpanelProvider mixpanelId={YOUR_MIXPANEL_ID_HERE} config={YOUR_MIXPANEL_CONFIG}>
    <Homepage />
  </MixpanelProvider>
);

When this is done, Mixpanel will register itself for your site and start tracking.

Tracking users

Mixpanel allows you to track user properties, to help with identifying users and some context about how they use your application.

To register a user and track it with Mixpanel, you can implement in the following way:

import React, { useEffect } from "react";

export const UserComponent = (props) => {
  // All Mixpanel utilites are exposed through a hook, so first we have to get those:
  const { identify, setUserProperties, incrementUserProperty } = useMixpanel();

  useEffect(() => {
    // This function registers a unique identifier for the current user, so that can link together individual sessions to one user in Mixpanel
    identify(props.user.id);

    // This function registers properties on the Mixpanel user object
    setUserProperties({
      email: props.user.email, // When logging user data, you might need to obfuscate the data by hashing it to be compliant with GDPR
      name: props.user.name,
      age: props.user.age,
    });
  }, [props.user]);

  const onClick = useCallback((event) => {
    // This function allows to increment a numeric user property by the amount specified in the configuration.
    incrementUserProperty({
      totalNumberOfClicks: 1,
    });
    props.handleClick(event);
  });

  return <button onClick={onClick}>Click me!</button>;
};

Tracking events

The main feature of Mixpanel is being able to track certain events happening within your application. You can track events like so:

import React, { useEffect, useCallback } from "react";

export const ButtonComponent = (props) => {
  const { register, track } = useMixpanel();

  useEffect(() => {
    // Registering super properties will register these properties for every event tracked in the application.
    register({
      date: props.date,
    });
    // You can also register super properties that will be tracked once in the following event. These will not override previous super properties
    registerOnce({
      something: "happened",
    });
  }, [props.date]);

  const onClick = useCallback((event) => {
    // By calling `track` you can fire custom events and track additional data along those:
    track("User clicked something", {});
    props.handleClick(event);
  });

  return <button onClick={onClick}>Click me!</button>;
};

Reset tracking

When someone logs out, you should clear all the super and user properties that you've registered with Mixpanel. You can do that by calling reset() from your components:

import React, { useCallback } from "react";

export const LogoutComponent = (props) => {
  const { reset } = useMixpanel();

  const onLogout = useCallback((event) => {
    // Reset Mixpanel to clear all super and user properties
    reset();
    props.onLogout();
  });

  return <button onClick={onLogout}>Log out</button>;
};