Mixpanel Class Reference

Inherits from NSObject
Declared in Mixpanel.h

Overview

Mixpanel API.

The primary interface for integrating Mixpanel with your app.

Use the Mixpanel class to set up your project and track events in Mixpanel Engagement. It now also includes a people property for accessing the Mixpanel People API.

// Initialize the API
Mixpanel *mixpanel = [Mixpanel sharedInstanceWithToken:@"YOUR API TOKEN"];

// Track an event in Mixpanel Engagement
[mixpanel track:@"Button Clicked"];

// Set properties on a user in Mixpanel People
[mixpanel identify:@"CURRENT USER DISTINCT ID"];
[mixpanel.people set:@"Plan" to:@"Premium"];

For more advanced usage, please see the Mixpanel iPhone Library Guide.

  people

Accessor to the Mixpanel People API object.

@property (atomic, readonly, strong) MixpanelPeople *people

Discussion

See the documentation for MixpanelDelegate below for more information.

Declared In

Mixpanel.h

  distinctId

The distinct ID of the current user.

@property (atomic, readonly, copy) NSString *distinctId

Discussion

A distinct ID is a string that uniquely identifies one of your users. By default, we’ll use the device’s advertisingIdentifier UUIDString, if that is not available we’ll use the device’s identifierForVendor UUIDString, and finally if that is not available we will generate a new random UUIDString. To change the current distinct ID, use the identify: method.

Declared In

Mixpanel.h

  alias

The alias of the current user.

@property (atomic, readonly, copy) NSString *alias

Discussion

An alias is another string that uniquely identifies one of your users. Typically, this is the user ID from your database. By using an alias you can link pre- and post-sign up activity as well as cross-platform activity under one distinct ID. To set the alias use the createAlias:forDistinctID: method.

Declared In

Mixpanel.h

  serverURL

The base URL used for Mixpanel API requests.

@property (nonatomic, copy) NSString *serverURL

Discussion

Useful if you need to proxy Mixpanel requests. Defaults to https://api.mixpanel.com.

Declared In

Mixpanel.h

  flushInterval

Flush timer’s interval.

@property (atomic) NSUInteger flushInterval

Discussion

Setting a flush interval of 0 will turn off the flush timer.

Declared In

Mixpanel.h

  flushOnBackground

Control whether the library should flush data to Mixpanel when the app enters the background.

@property (atomic) BOOL flushOnBackground

Discussion

Defaults to YES. Only affects apps targeted at iOS 4.0, when background task support was introduced, and later.

Declared In

Mixpanel.h

  shouldManageNetworkActivityIndicator

Controls whether to show spinning network activity indicator when flushing data to the Mixpanel servers.

@property (atomic) BOOL shouldManageNetworkActivityIndicator

Discussion

Defaults to YES.

Declared In

Mixpanel.h

  checkForNotificationsOnActive

Controls whether to automatically check for notifications for the currently identified user when the application becomes active.

@property (atomic) BOOL checkForNotificationsOnActive

Discussion

Defaults to YES. Will fire a network request on applicationDidBecomeActive to retrieve a list of valid notifications for the currently identified user.

Declared In

Mixpanel.h

  checkForVariantsOnActive

Controls whether to automatically check for A/B test variants for the currently identified user when the application becomes active.

@property (atomic) BOOL checkForVariantsOnActive

Discussion

Defaults to YES. Will fire a network request on applicationDidBecomeActive to retrieve a list of valid variants for the currently identified user.

Declared In

Mixpanel.h

  showNotificationOnActive

Controls whether to automatically check for and show in-app notifications for the currently identified user when the application becomes active.

@property (atomic) BOOL showNotificationOnActive

Discussion

Defaults to YES.

Declared In

Mixpanel.h

  useIPAddressForGeoLocation

Controls whether to automatically send the client IP Address as part of event tracking. With an IP address, geo-location is possible down to neighborhoods within a city, although the Mixpanel Dashboard will just show you city level location specificity. For privacy reasons, you may be in a situation where you need to forego effectively having access to such granular location information via the IP Address.

@property (atomic) BOOL useIPAddressForGeoLocation

Discussion

Defaults to YES.

Declared In

Mixpanel.h

  enableVisualABTestAndCodeless

Controls whether to enable the visual test designer for A/B testing and codeless on mixpanel.com. You will be unable to edit A/B tests and codeless events with this disabled, however previously created A/B tests and codeless events will still be delivered.

@property (atomic) BOOL enableVisualABTestAndCodeless

Discussion

Defaults to YES.

Declared In

Mixpanel.h

  enableLogging

Controls whether to enable the run time debug logging at all levels. Note that the Mixpanel SDK uses Apple System Logging to forward log messages to STDERR, this also means that mixpanel logs are segmented by log level. Settings this to YES will enable Mixpanel logging at the following levels:

@property (atomic) BOOL enableLogging

Discussion

  • Error - Something has failed
  • Warning - Something is amiss and might fail if not corrected
  • Info - The lowest priority that is normally logged, purely informational in nature
  • Debug - Information useful only to developers, and normally not logged.

Defaults to NO.

Declared In

Mixpanel.h

  miniNotificationPresentationTime

Determines the time, in seconds, that a mini notification will remain on the screen before automatically hiding itself.

@property (atomic) CGFloat miniNotificationPresentationTime

Discussion

Defaults to 6.0.

Declared In

Mixpanel.h

  minimumSessionDuration

The minimum session duration (ms) that is tracked in automatic events.

@property (atomic) UInt64 minimumSessionDuration

Discussion

The default value is 10000 (10 seconds).

Declared In

Mixpanel.h

  maximumSessionDuration

The maximum session duration (ms) that is tracked in automatic events.

@property (atomic) UInt64 maximumSessionDuration

Discussion

The default value is UINT64_MAX (no maximum session duration).

Declared In

Mixpanel.h

  delegate

The a MixpanelDelegate object that can be used to assert fine-grain control over Mixpanel network activity.

@property (atomic, weak) id<MixpanelDelegate> delegate

Discussion

Using a delegate is optional. See the documentation for MixpanelDelegate below for more information.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:

Returns (and creates, if needed) a singleton instance of the API.

+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken

Parameters

apiToken

your project token

Discussion

This method will return a singleton instance of the Mixpanel class for you using the given project token. If an instance does not exist, this method will create one using initWithToken:launchOptions:andFlushInterval:. If you only have one instance in your project, you can use sharedInstance to retrieve it.

[[Mixpanel sharedInstance]](#//api/name/sharedInstance) track:@"Something Happened"]];

If you are going to use this singleton approach, sharedInstanceWithToken: must be the first call to the Mixpanel class, since it performs important initializations to the API.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:launchOptions:

Initializes a singleton instance of the API, uses it to track launchOptions information, and then returns it.

+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions

Parameters

apiToken

your project token

launchOptions

your application delegate’s launchOptions

Discussion

This is the preferred method for creating a sharedInstance with a mixpanel like above. With the launchOptions parameter, Mixpanel can track referral information created by push notifications.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:launchOptions:trackCrashes:automaticPushTracking:

Initializes a singleton instance of the API, uses it to track launchOptions information, and then returns it.

+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken launchOptions:(NSDictionary *)launchOptions trackCrashes:(BOOL)trackCrashes automaticPushTracking:(BOOL)automaticPushTracking

Parameters

apiToken

your project token

launchOptions

your application delegate’s launchOptions

trackCrashes

whether or not to track crashes in Mixpanel. may want to disable if you’re seeing issues with your crash reporting for either signals or exceptions

automaticPushTracking

whether or not to automatically track pushes sent from Mixpanel

Discussion

This is the preferred method for creating a sharedInstance with a mixpanel like above. With the launchOptions parameter, Mixpanel can track referral information created by push notifications.

Declared In

Mixpanel.h

+ sharedInstance

Returns a previously instantiated singleton instance of the API.

+ (nullable Mixpanel *)sharedInstance

Discussion

The API must be initialized with sharedInstanceWithToken: or initWithToken:launchOptions:andFlushInterval before calling this class method. This method will return nil if there are no instances created. If there is more than one instace, it will return the first one that was created by using sharedInstanceWithToken: or initWithToken:launchOptions:andFlushInterval:.

Declared In

Mixpanel.h

– initWithToken:launchOptions:flushInterval:trackCrashes:

Initializes an instance of the API with the given project token. This also sets it as a shared instance so you can use sharedInstance or sharedInstanceWithToken: to retrieve this object later.

- (instancetype)initWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions flushInterval:(NSUInteger)flushInterval trackCrashes:(BOOL)trackCrashes

Parameters

apiToken

your project token

launchOptions

optional app delegate launchOptions

flushInterval

interval to run background flushing

trackCrashes

whether or not to track crashes in Mixpanel. may want to disable if you’re seeing issues with your crash reporting for either signals or exceptions

Discussion

Creates and initializes a new API object. See also sharedInstanceWithToken:.

Declared In

Mixpanel.h

– initWithToken:launchOptions:flushInterval:trackCrashes:automaticPushTracking:

Initializes an instance of the API with the given project token. This also sets it as a shared instance so you can use sharedInstance or sharedInstanceWithToken: to retrieve this object later.

- (instancetype)initWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions flushInterval:(NSUInteger)flushInterval trackCrashes:(BOOL)trackCrashes automaticPushTracking:(BOOL)automaticPushTracking

Parameters

apiToken

your project token

launchOptions

optional app delegate launchOptions

flushInterval

interval to run background flushing

trackCrashes

whether or not to track crashes in Mixpanel. may want to disable if you’re seeing issues with your crash reporting for either signals or exceptions

automaticPushTracking

whether or not to automatically track pushes sent from Mixpanel

Discussion

Creates and initializes a new API object. See also sharedInstanceWithToken:.

Declared In

Mixpanel.h

– initWithToken:launchOptions:andFlushInterval:

Initializes an instance of the API with the given project token.

- (instancetype)initWithToken:(NSString *)apiToken launchOptions:(nullable NSDictionary *)launchOptions andFlushInterval:(NSUInteger)flushInterval

Parameters

apiToken

your project token

launchOptions

optional app delegate launchOptions

flushInterval

interval to run background flushing

Discussion

Creates and initializes a new API object. See also sharedInstanceWithToken:.

Declared In

Mixpanel.h

– initWithToken:andFlushInterval:

Initializes an instance of the API with the given project token.

- (instancetype)initWithToken:(NSString *)apiToken andFlushInterval:(NSUInteger)flushInterval

Parameters

apiToken

your project token

flushInterval

interval to run background flushing

Discussion

Supports for the old initWithToken method format but really just passes launchOptions to the above method as nil.

Declared In

Mixpanel.h

– identify:

Sets the distinct ID of the current user.

- (void)identify:(NSString *)distinctId

Parameters

distinctId

string that uniquely identifies the current user

Discussion

As of version 2.3.1, Mixpanel will choose a default distinct ID based on whether you are using the AdSupport.framework or not.

If you are not using the AdSupport Framework (iAds), then we use the [UIDevice currentDevice].identifierForVendor (IFV) string as the default distinct ID. This ID will identify a user across all apps by the same vendor, but cannot be used to link the same user across apps from different vendors.

If you are showing iAds in your application, you are allowed use the iOS ID for Advertising (IFA) to identify users. If you have this framework in your app, Mixpanel will use the IFA as the default distinct ID. If you have AdSupport installed but still don’t want to use the IFA, you can define the MIXPANEL_NO_IFA preprocessor flag in your build settings, and Mixpanel will use the IFV as the default distinct ID.

If we are unable to get an IFA or IFV, we will fall back to generating a random persistent UUID.

For tracking events, you do not need to call identify: if you want to use the default. However, Mixpanel People always requires an explicit call to identify:. If calls are made to set:, increment or other MixpanelPeople methods prior to calling identify:, then they are queued up and flushed once identify: is called.

If you’d like to use the default distinct ID for Mixpanel People as well (recommended), call identify: using the current distinct ID: [mixpanel identify:mixpanel.distinctId].

Declared In

Mixpanel.h

– identify:usePeople:

Sets the distinct ID of the current user. With the option of only updating the distinct ID value and not the Mixpanel People distinct ID.

- (void)identify:(NSString *)distinctId usePeople:(BOOL)usePeople

Parameters

distinctId

string that uniquely identifies the current user

usePeople

bool controls whether or not to set the people distinctId to the event distinctId

Discussion

This method is not intended to be used unless you wish to prevent updating the Mixpanel People distinct ID value by passing a value of NO to the usePeople param. This can be useful if the user wishes to prevent People updates from being sent until the identify method is called.

Declared In

Mixpanel.h

– track:

Tracks an event.

- (void)track:(NSString *)event

Parameters

event

event name

Declared In

Mixpanel.h

– track:properties:

Tracks an event with properties.

- (void)track:(NSString *)event properties:(nullable NSDictionary *)properties

Parameters

event

event name

properties

properties dictionary

Discussion

Properties will allow you to segment your events in your Mixpanel reports. Property keys must be NSString objects and values must be NSString, NSNumber, NSNull, NSArray, NSDictionary, NSDate or NSURL objects. If the event is being timed, the timer will stop and be added as a property.

Declared In

Mixpanel.h

– registerSuperProperties:

Registers super properties, overwriting ones that have already been set.

- (void)registerSuperProperties:(NSDictionary *)properties

Parameters

properties

properties dictionary

Discussion

Super properties, once registered, are automatically sent as properties for all event tracking calls. They save you having to maintain and add a common set of properties to your events. Property keys must be NSString objects and values must be NSString, NSNumber, NSNull, NSArray, NSDictionary, NSDate or NSURL objects.

Declared In

Mixpanel.h

– registerSuperPropertiesOnce:

Registers super properties without overwriting ones that have already been set.

- (void)registerSuperPropertiesOnce:(NSDictionary *)properties

Parameters

properties

properties dictionary

Discussion

Property keys must be NSString objects and values must be NSString, NSNumber, NSNull, NSArray, NSDictionary, NSDate or NSURL objects.

Declared In

Mixpanel.h

– registerSuperPropertiesOnce:defaultValue:

Registers super properties without overwriting ones that have already been set unless the existing value is equal to defaultValue.

- (void)registerSuperPropertiesOnce:(NSDictionary *)properties defaultValue:(nullable id)defaultValue

Parameters

properties

properties dictionary

defaultValue

overwrite existing properties that have this value

Discussion

Property keys must be NSString objects and values must be NSString, NSNumber, NSNull, NSArray, NSDictionary, NSDate or NSURL objects.

Declared In

Mixpanel.h

– unregisterSuperProperty:

Removes a previously registered super property.

- (void)unregisterSuperProperty:(NSString *)propertyName

Parameters

propertyName

array of property name strings to remove

Discussion

As an alternative to clearing all properties, unregistering specific super properties prevents them from being recorded on future events. This operation does not affect the value of other super properties. Any property name that is not registered is ignored.

Note that after removing a super property, events will show the attribute as having the value undefined in Mixpanel until a new value is registered.

Declared In

Mixpanel.h

– clearSuperProperties

Clears all currently set super properties.

- (void)clearSuperProperties

Declared In

Mixpanel.h

– currentSuperProperties

Returns the currently set super properties.

- (NSDictionary *)currentSuperProperties

Declared In

Mixpanel.h

– timeEvent:

Starts a timer that will be stopped and added as a property when a corresponding event is tracked.

- (void)timeEvent:(NSString *)event

Parameters

event

a string, identical to the name of the event that will be tracked

Discussion

This method is intended to be used in advance of events that have a duration. For example, if a developer were to track an “Image Upload” event she might want to also know how long the upload took. Calling this method before the upload code would implicitly cause the track call to record its duration.

// begin timing the image upload
[mixpanel timeEvent:@"Image Upload"];

// upload the image
[self uploadImageWithSuccessHandler:^{

    // track the event
    [mixpanel track:@"Image Upload"];
}];

Declared In

Mixpanel.h

– eventElapsedTime:

Retrieves the time elapsed for the named event since timeEvent: was called.

- (double)eventElapsedTime:(NSString *)event

Parameters

event

the name of the event to be tracked that was passed to timeEvent:

Declared In

Mixpanel.h

– clearTimedEvents

Clears all current event timers.

- (void)clearTimedEvents

Declared In

Mixpanel.h

– reset

Clears all stored properties and distinct IDs. Useful if your app’s user logs out.

- (void)reset

Declared In

Mixpanel.h

– flush

Uploads queued data to the Mixpanel server.

- (void)flush

Discussion

By default, queued data is flushed to the Mixpanel servers every minute (the default for flushInterval), and on background (since flushOnBackground is on by default). You only need to call this method manually if you want to force a flush at a particular moment.

Declared In

Mixpanel.h

– flushWithCompletion:

Calls flush, then optionally archives and calls a handler when finished.

- (void)flushWithCompletion:(nullable void ( ^ ) ( void ))handler

Parameters

handler

completion handler to be called after flush completes

Discussion

When calling flush manually, it is sometimes important to verify that the flush has finished before further action is taken. This is especially important when the app is in the background and could be suspended at any time if protocol is not followed. Delegate methods like application:didReceiveRemoteNotification:fetchCompletionHandler: are called when an app is brought to the background and require a handler to be called when it finishes.

Declared In

Mixpanel.h

– archive

Writes current project info, including distinct ID, super properties and pending event and People record queues to disk.

- (void)archive

Discussion

This state will be recovered when the app is launched again if the Mixpanel library is initialized with the same project token. You do not need to call this method. The library listens for app state changes and handles persisting data as needed. It can be useful in some special circumstances, though, for example, if you’d like to track app crashes from main.m.

Declared In

Mixpanel.h

– createAlias:forDistinctID:

Creates a distinct_id alias from alias to original id.

- (void)createAlias:(NSString *)alias forDistinctID:(NSString *)distinctID

Parameters

alias

the new distinct_id that should represent original

distinctID

the old distinct_id that alias will be mapped to

Discussion

This method is used to map an identifier called an alias to the existing Mixpanel distinct id. This causes all events and people requests sent with the alias to be mapped back to the original distinct id. The recommended usage pattern is to call createAlias: and then identify: (with their new user ID) when they log in the next time. This will keep your signup funnels working correctly.

// This makes the current ID (an auto-generated GUID)
// and 'Alias' interchangeable distinct ids.
[mixpanel createAlias:@"Alias"
    forDistinctID:mixpanel.distinctId];

// You must call identify if you haven't already
// (e.g., when your app launches).
[mixpanel identify:mixpanel.distinctId];

Declared In

Mixpanel.h

– createAlias:forDistinctID:usePeople:

Creates a distinct_id alias from alias to original id.

- (void)createAlias:(NSString *)alias forDistinctID:(NSString *)distinctID usePeople:(BOOL)usePeople

Parameters

alias

the new distinct_id that should represent original

distinctID

the old distinct_id that alias will be mapped to

usePeople

bool controls whether or not to set the people distinctId to the event distinctId

Discussion

This method is not intended to be used unless you wish to prevent updating the Mixpanel People distinct ID value by passing a value of NO to the usePeople param. This can be useful if the user wishes to prevent People updates from being sent until the identify method is called.

Declared In

Mixpanel.h

– libVersion

Returns the Mixpanel library version number as a string, e.g. “3.2.3”.

- (NSString *)libVersion

Declared In

Mixpanel.h

+ libVersion

Returns the Mixpanel library version number as a string, e.g. “3.2.3”.

+ (NSString *)libVersion

Declared In

Mixpanel.h

– showNotificationWithID:

Shows the notification of the given id.

- (void)showNotificationWithID:(NSUInteger)ID

Parameters

ID

notification id

Discussion

You do not need to call this method on the main thread.

Declared In

Mixpanel.h

– showNotificationWithType:

Shows a notification with the given type if one is available.

- (void)showNotificationWithType:(NSString *)type

Parameters

type

The type of notification to show, either @“mini”, or @“takeover”

Discussion

You do not need to call this method on the main thread.

Declared In

Mixpanel.h

– showNotification

Shows a notification if one is available.

- (void)showNotification

Discussion

You do not need to call this method on the main thread.

Declared In

Mixpanel.h

– joinExperiments

Join any experiments (A/B tests) that are available for the current user.

- (void)joinExperiments

Discussion

Mixpanel will check for A/B tests automatically when your app enters the foreground. Call this method if you would like to to check for, and join, any experiments are newly available for the current user.

You do not need to call this method on the main thread.

Declared In

Mixpanel.h

– joinExperimentsWithCallback:

Join any experiments (A/B tests) that are available for the current user.

- (void)joinExperimentsWithCallback:(nullable void ( ^ ) ( void ))experimentsLoadedCallback

Parameters

experimentsLoadedCallback

callback to be called after experiments joined and applied

Discussion

Same as joinExperiments but will fire the given callback after all experiments have been loaded and applied.

Declared In

Mixpanel.h

  __deprecated

Current user’s name in Mixpanel Streams.

@property (nullable, atomic, copy) NSString *__deprecated

Declared In

Mixpanel.h