Unity SDK - Quick Start Guide

Installing the library

You can get the library by downloading the latest MixpanelSDK.unitypackage file from GitHub.

To import MixpanelSDK.unitypackage into Unity, select Assets > Custom Package... and import the MixpanelSDK.unitypackage file. Alternately, you can locate the MixpanelSDK.unitypackage file in your file system and double-click to launch.

Initializing the library

To start tracking with the Mixpanel Unity library, you must first initialize it with your project token. You can find your token by clicking your name in the upper righthand corner of your Mixpanel project and selecting Settings from the dropdown.

Add Mixpanel Component

To initialize the library, first add a new Mixpanel component to your Unity GameObject. Then, enter your project token into the Token and Debug Token input fields within the inspector.

You have the option to provide different tokens for debug and production builds of your project. Keeping data sets separate is important to maintain the integrity of the metrics you’re tracking with Mixpanel. It’s very easy to prevent these data sets from commingling, but hard to disentangle, so taking time up front is well worth it. First, create two separate Mixpanel projects – a "Production" project and a "Debug" project (Mixpanel doesn’t limit the number of projects you can use). Then, you can enter your "Production" and "Debug" project tokens into the Token and Debug Token input fields respectively.

C#

Once you've initialized the library with your project token, you can import Mixpanel into your code using the mixpanel namespace.

using mixpanel;

// Then, you can track events with
Mixpanel.Track("Plan Selected");

Sending your first event

Once you've initialized the library, you can track an event using Mixpanel.Track() with the event name and properties.

var props = new Value();
props["Gender"] = "Female";
props["Plan"] = "Premium";

Mixpanel.Track("Plan Selected", props);

Timing events

You can track the time it took for an action to occur, such as an image upload or a comment post, using Mixpanel.StartTimedEvent This will mark the "start" of your action, which you can then finish with a track call. The time duration is then recorded in the "Duration" property.

Mixpanel.StartTimedEvent("Image Upload");

Mixpanel.Track("Image Upload");

Super properties

It's very common to have certain properties that you want to include with each event you send. Generally, these are things you know about the user rather than about a specific event—for example, the user's age, gender, or source.

To make things easier, you can register these properties as super properties. If you do, we will automatically include them with all tracked events. Super properties are saved to device storage, and will persist across invocations of your app.

To set super properties, call Mixpanel.Register.

// Send a "User Type: Paid" property will be sent
// with all future track calls.
Mixpanel.Register("User Type", "Paid");

Going forward, whenever you track an event, super properties will be included as properties. For instance, if you call

var props = new Value();
props["signup_button"] = "test12";

Mixpanel.Track("signup", props);

after making the above call to Mixpanel.Register, it is just like adding the properties directly:

var props = new Value();
props["signup_button"] = "test12";
props["User Type"] = "Paid";

Mixpanel.Track("signup", props);

Setting super properties once and only once

If you want to store a super property only once (often for things like ad campaign or source), you can use Mixpanel.RegisterOnce. This function behaves like Mixpanel.Register and has the same interface, but it doesn't override super properties you've already saved.

Mixpanel.RegisterOnce("source", "ad-01");

This means that it's safe to call Mixpanel.RegisterOnce with the same property on every app load, and it will only set it if the super property doesn't exist.

Managing user identity

The Mixpanel library will assign a default unique identifier (we call it a "distinct ID") to each unique user who installs your application. This distinct ID is saved to device storage so that it will persist across sessions.

If you choose, you can assign your own user IDs. This is particularly useful if a user is using your app on multiple platforms (both web and mobile, for example). To assign your own distinct_ids, you can use Mixpanel.Identify.

// Ensure all future events sent from
// the library will have the distinct_id 13793
Mixpanel.Identify("13793");

Calling Mixpanel.Identify with a new ID will change the distinctID stored on the device. Updates to user profiles are queued on the device until identify is called.

Combining anonymous and identifiable user data

It's important to send the same distinct_id with each event that an individual user triggers. Events recorded with different distinct_ids will be treated in Mixpanel as if they were performed by different users.

There are times when it can be convenient to start referring to a user by a different identifier in your implementation. The most common case is after registration, when a user switches from being an anonymous user (with an anonymous distinct_id) to an authenticated user with an (authenticated id). In this case, you can create an Alias for the user to keep the distinct_id consistent. An alias is a string stored in a Mixpanel lookup table that is associated with an anonymous distinct_id. Once written, aliases are not editable. Any data sent to Mixpanel with an alias as the distinct_id will be remapped and written to disk using the alias's corresponding anonymous distinct_id. This allows you to start identifying a user by an authenticated id without changing the distinct_id that is ultimately written in Mixpanel.

// This makes the current ID (by default an auto-generated GUID)
// and '13793' interchangeable distinct ids.
Mixpanel.Alias("13793");

The recommended usage pattern is to call both Mixpanel.Alias and Mixpanel.Identify (with the Mixpanel generated distinct ID, as shown in the example above) when the user signs up, and only Mixpanel.Identify (with the aliased user ID) on future log ins. This will keep your signup funnels working correctly.

If you use Mixpanel.Alias, we recommend only calling it once during the lifetime of the user.

Storing user profiles

In addition to events, you can store user profiles in Mixpanel's People Analytics product. Profiles are persistent sets of properties that describe a user—things like name, email address, and signup date. You can use profiles to explore and segment users by who they are, rather than what they did. You can also use profiles to send messages, such as emails, SMS, or push notifications.

Before you send profile updates, you must call Mixpanel.Identify. This ensures that you only have registered users saved in the system.

Setting profile properties

You can set properties on a user profile with Mixpanel.people.Set.

// mixpanel identify: must be called before
// people properties can be set
Mixpanel.Identify("13793");

// Sets user 13793's "Plan" attribute to "Premium"
Mixpanel.people.Set("Plan", "Premium");

This will set a "Plan" property, with a value "Premium," on user 13793's profile. If there isn't a profile with distinct_id 13793 in Mixpanel already, a new profile will be created. If user 13793 already has a property named "Plan" in their profile, the old value will be overwritten with "Premium."

Incrementing numeric properties

You can use Mixpanel.people.Increment to change the current value of numeric properties. This is useful when you want to keep a running tally of things, such as games played, messages sent, or points earned.

// Here we increment the user's point count by 500.
Mixpanel.people.Increment("point count", 500);

Other types of profile updates

There are a few other types of profile updates. To learn more, please see the Full API reference.

Tracking revenue

Mixpanel makes it easy to analyze the revenue you earn from individual customers. By associating charges with user profiles, you can compare revenue across different customer segments and calculate things like lifetime value.

You can track a single transaction with Mixpanel.people.TrackCharge. This call will add transactions to the individual user profile, which will also be reflected in the Mixpanel Revenue report.

// Make sure identify has been called before making revenue
// updates
Mixpanel.Identify("13793");

// Tracks $100 in revenue for user 13793
Mixpanel.people.TrackCharge(100);

// Refund this user 50 dollars
Mixpanel.people.TrackCharge(-50);

// Tracks $25 in revenue for user 13793 on the 2nd of
// January
var props = new Value();
props["time"] = "2012-01-02T00:00:00";

Mixpanel.people.TrackCharge(25, props);

Registering for push notifications

The Mixpanel library includes support for sending iOS push notification device tokens to Mixpanel. Once you send a device token, you can use Mixpanel to send push notifications to your app.

Android push notifications are not supported through this Mixpanel library or through the Unity Notification Services class.

You can send a device token to Mixpanel from the Unity NotificationServices.RegisterForNotifications class, using Mixpanel.people.PushDeviceToken

using UnityEngine;
using System.Collections;
using NotificationServices = UnityEngine.iOS.NotificationServices;
using NotificationType = UnityEngine.iOS.NotificationType;
using mixpanel;

public class NotificationRegistrationExample : MonoBehaviour {
  bool tokenSent;

  void Start() {
    tokenSent = false;

    NotificationServices.RegisterForNotifications(
    NotificationType.Alert |
    NotificationType.Badge |
    NotificationType.Sound);
  }

  void Update () {
    if (!tokenSent) {
      byte[] token = NotificationServices.deviceToken;
      if (token != null) {

        // Make sure identify has been called
        // before sending a device token.
        Mixpanel.Identify("13793");

        // This sends the deviceToken to Mixpanel
        #if UNITY_IOS
          Mixpanel.people.PushDeviceToken = token;
        #endif

        tokenSent = true;
      }
    }
  }
}