Mixpanel SDKs: Unity

Getting Started

The Full API Reference, Library Source Code, and an Example Application is documented in our GitHub repo.

⚠️

Unity SDK does not currently support Simplified ID Merge.

Installing the Library

This library can be installed using the unity package manager system with git. We support Unity 2018.3 and above. For older versions of Unity, you need to have .NET 4.x Equivalent selected as the scripting runtime version in your editor settings.

To install the library in your Unity project, declare it as a dependency in the ./Packages/manifest.json file of your project:

{
  ...
  "dependencies": {
    //add latest library version
    "com.mixpanel.unity": "https://github.com/mixpanel/mixpanel-unity.git#master",
    //point to specific library version
    "com.mixpanel.unity": "https://github.com/mixpanel/mixpanel-unity.git#v3.5.1",
  }
  ...
}

Then open Unity and the library should download automatically along with any other packages declared in your dependencies.

Alternatively you can go to the releases page and download the .unitypackage file and manually install the package using Unity.

After installing the package, open the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel), then enter your project token into the Token and Debug Token input fields within the inspector to initialize Mixpanel:

Please note if you prefer to initialize Mixpanel manually, you can select the Manual Initialization in the settings and call Mixpanel.Init() to initialize.

Once you’ve initialized the library with your project token, import Mixpanel into your code using the mixpanel namespace to start using it:

// import mixpanel package to your code
using mixpanel;
 
// start using library methods
Mixpanel.Track("event_name");

Sending Events

Use Mixpanel.Track() to send an event by providing the event name and any event properties. This will trigger a request to the /track API endpoint to ingest the event into your project.

The /track endpoint will only validate events with timestamps within the last 5 days of the request. Events with timestamps older than 5 days will not be ingested. See below on best practices for historical imports.

Example Usage

// define event properties
var props = new Value();
props["location"] = "us";
props["Plan"] = "Premium";
 
//track "some_event" with your event props
Mixpanel.Track("some_event", 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.

Example Usage

// start the timer for the event "Image Upload"
Mixpanel.StartTimedEvent("Image Upload");
 
// 20 seconds later...
 
// track "Image Upload" event with Duration event prop set to 20
Mixpanel.Track("Image Upload");

Flushing Events

To preserve battery life and customer bandwidth, the Mixpanel library doesn’t send the events you record immediately. Instead, it sends batches to the Mixpanel servers every 60 seconds while your application is running, as well as when the application transitions to the background.

Call Mixpanel.FlushQueue() manually if you want to force a flush at a particular moment.

Example Usage

Upload queued data to the Mixpanel server
Mixpanel.FlushQueue();

Flush Interval You can update the default flush interval from 60 seconds to another interval by setting a new Flush Interval value in Edit -> Project Settings -> Mixpanel.

Importing Historical Events

The Unity SDK is a tracking SDK designed for real-time tracking in a client-side environment. Calling Mixpanel.Track() triggers a request to our /track API endpoint, which will validate for events with a timestamp that is within the last 5 days of the request. Events older than 5 days will not be ingested.

For bulk import of historical events older than 5 days, we will need to use the /import API endpoint which is optimized for scripting and supports ingesting historical data. We recommend the Python SDK (see the .import_data() function) and mixpanel-utils module (see the import_events() function) which both leverages the /import API for event ingestion.

Setting Super Properties

Super properties are global event properties that you define once and apply to all events.

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. Mixpanel already stores some information as super properties by default; see a full list of Mixpanel default properties here.

To register super properties, call Mixpanel.Register().

Use Mixpanel.RegisterOnce() to register super properties without overwriting existing values.

Example Usage

// register "name" as a super property
Mixpanel.Register("name", "Sam");
 
// track "some_event"
// "name" event prop is included in the event
Mixpanel.track("some_event");
 
// ignored since "name" already exists
Mixpanel.RegisterOnce("name", "Samantha");

Our libraries store your super properties in local storage. They will persist so long as the app is installed (between launches and updates). Uninstalling the app will remove the super properties.

See more methods related to super properties in the complete library reference here.

Managing User Identity

You can handle the identity of a user using the Mixpanel.Identify() and Mixpanel.Reset() methods. Learn more about identity management and identifying users.

Identify

⚠️

We recommend against calling Mixpanel.Identify() for anonymous visitors to your site.

Call Mixpanel.Identify() when you know the identity of the current user, passing in their user ID as an argument. This is typically at account registration and at log in.

Example Usage

// user logs in and tracks a sign in event
 Mixpanel.Track('sign in');
 
// upon sign in, identify the user with their ID
// ensure future events sent from the user have distinct_id 12345
Mixpanel.Identify('12345');

Call Reset at Logout

Call Mixpanel.Reset() to clear data attributed to a user when they logout. This will clear the local storage and allows you to handle multiple users on a single device.

Example Usage

// your user logs out and tracks a log out event
Mixpanel.Track('log out');
 
// clear local storage and generate new distinct_id
Mixpanel.Reset();

Storing User Profiles

Once your users are identified, create user profiles by setting profile properties to describe them. Example profile properties include “name”, “email”, “company”, and any other demographic details about the user.

The Unity SDK provides a few methods for setting profile properties under the People class. These methods will trigger requests to the /engage API endpoint.

Setting Profile Properties

You must call .identify() before setting profile properties in order to associate the profile properties you set with the target user. If identify is not called, the profile update will be queued for ingestion until an identify call is made.

Set profile properties on a user profile by calling the Mixpanel.People.Set method.

If a profile property already exist, if will be overwritten with the latest value provided in the method. If a profile property does not exist, it will be added to the profile.

Example Usage

// You must call identify to associate the profile update with the user
// Sets user's "Plan" attribute to "Premium"
Mixpanel.Identify("12345");
Mixpanel.People.Set("Plan", "Premium");
 
// Update "plan" from "Premium" to "Enterprise"
Mixpanel.People.Set("Plan", "Enterprise");

Other Types of Profile Updates

There are a few other methods for setting profile properties. See a complete reference of the available methods here

A few commonly used people methods are highlighted below:

The .People.SetOnce() method set profile properties only if they do not exist yet. If it is setting a profile property that already exists, it will be ignored.

Use this method if you want to set profile properties without the risk of overwriting existing data.

Example Usage

// set profile properties for user "1234"
Mixpanel.Identify('1234');
Mixpanel.People.Set('name':'sam');
 
// will be ignored since "name" already exists
Mixpanel.People.SetOnce('name', 'samantha');
 
// set "location" group prop since it does not exist
Mixpanel.People.SetOnce('location', 'us');

The .People.Append() method append values to a list profile property.

Use this method to add additional values to an existing list property instead of redefining the entire list.

Example Usage

// set profile properties for user "1234"
Mixpanel.Identify('1234');
var roles = new string[] {'sales','engineer'};
Mixpanel.People.Set({
    'name':'sam',
    'roles': roles
});
 
// add "legal" to "roles"  
// new role values are ['sales','engineer','legal']
Mixpanel.People.Append('roles', 'legal');
 
// .append() allows duplicates
// new "roles" values are ['sales','engineer','legal', 'legal']
Mixpanel.People.Append('roles', 'legal');

The .People.Union() method append new values to a list property, excluding duplicates.

Use this method to create a list profile property that only contains unique values without duplicates.

Example Usage

// set profile properties for user "1234"
Mixpanel.Identify('1234');
var roles = new string[] {'sales','engineer'};
Mixpanel.People.Set({
    'name':'sam',
    'roles': roles
});
 
// append "engineer" to "roles"
// will be ignored since "engineer" already exists in "roles"
Mixpanel.People.Union('roles', 'engineer');
 
// append "legal" to "roles"
// new role values are ['sales','engineer','legal']
Mixpanel.People.Union('roles', 'legal');

The .People.Increment() method increments a numeric property by a whole number.

Use this method to add to or subtract from your numeric property based on its current value.

Example Usage

// set profile properties for user "1234"
Mixpanel.Identify('1234');
Mixpanel.People.Set({
    'name':'sam',
    'age': 25
});
 
// increment "age" by 2
Mixpanel.People.Increment('age',2);
 
// use negative number to decrement
// decrement "age" by 5
Mixpanel.People.Increment('age',-5);

Group Analytics

Read more about Group Analytics before proceeding. You will need to have the group key defined in your project settings first.

Mixpanel Group Analytics is a paid add-on that allows behavioral data analysis by selected groups, as opposed to individual users.

A group is identified by the group_key and group_id.

group_key is the event property that connects event data to a group. (e.g. company)
group_id is the identifier for a specific group. (e.g. mixpanel,company_a,company_b, etc.)

Sending Group Identifiers With Events

All events must have the group key as an event property in order to be attributed to a group. Without the group key, an event cannot be attributed to a group.

To send group identifiers with your events, set the group_key as an event property with the group_id as the value.

Example Usage

// set group key "company" as event prop
// with "mixpanel" as value
var props = new Value();
props["company"] = "mixpanel";
 
//track "some_event" with your event props
// this event is associated with the mixpanel company group
Mixpanel.Track("some_event", props);

Multiple Groups

An event can be attributed to multiple groups by passing in the group_key value as a list of multiple group_id values.

Example Usage

// set group key "company" as event prop
// with "mp-eu" and "mp-us" as value
var props = new Value();
var companies = new string[] {"mp-eu","mp-us"};
props["company"] = companies;
 
//track "some_event" with your event props
// this event is associated with the mp-eu and mp-us company group
Mixpanel.Track("some_event", props);

Adding Group Identifiers to User Profiles

To connect group information to a user profile, include the group_key and group_id as a user profile property using the People.Set() call.

Example Usage

// set group key "company" as a user prop
// with group id "mixpanel" as value
Mixpanel.Identify("12345");
Mixpanel.People.Set("company", "mixpanel");

Privacy-Friendly Tracking

You have control over the data you send to Mixpanel. The Unity SDK provide methods to help you protect user data.

Learn more about Privacy.

Opt Out of Tracking

The Unity SDK is initialized with tracking enabled by default. Use the .OptOutTracking() method to opt the user out of data tracking and local storage for the current Mixpanel instance.

Example Usage

//send "some_event"
Mixpanel.Track("some_event");
 
// opt user out of tracking
// SDK is prevented from sending any data
Mixpanel.OptOutTracking();
 
// this track call will not work
Mixpanel.Track("some_event");

Opt Out By Default

You can initialize the library with users opted out of tracking by default using the IsTracking configuration. Once the user is ready to be tracked, call .optInTracking() to start tracking.

Example Usage

// turn off tracking
MixpanelStorage.IsTracking = false;
 
//opt back into tracking
Mixpanel.OptInTracking();

EU Data Residency

Route data to Mixpanel’s EU servers by setting the API Host Address to https://api-eu.mixpanel.com/ when configuring the library under the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel).

India Data Residency

Route data to Mixpanel’s EU servers by setting the API Host Address to https://api-in.mixpanel.com/ when configuring the library under the unity project settings menu for Mixpanel (Edit -> Project Settings -> Mixpanel).

Release History

See all releases.

Flutter Python

Was this page useful?