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.

  persistence

@property (atomic, readonly, strong) MixpanelPersistence *persistence

  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

  anonymousId

The default anonymous Id / distinct Id given to the events before identify.

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

Discussion

A default distinct ID is a string that uniquely identifies the anonymous activity. 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.

Declared In

Mixpanel.h

  userId

The user ID with which identify: is called with.

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

Discussion

This is null until identify: is called and is set to the id with which identify is called with.

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

  hadPersistedDistinctId

A flag which says if a distinctId is already in peristence from old sdk Defaults to NO.

@property (nonatomic, assign) BOOL hadPersistedDistinctId

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

  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

  useUniqueDistinctId

Controls whether or not to use a unique device identifier for the Mixpanel Distinct ID

@property (atomic) BOOL useUniqueDistinctId

Discussion

Defaults to NO

Declared In

Mixpanel.h

  trackAutomaticEventsEnabled

This allows enabling or disabling collecting common mobile events If this is not set, it will query the Autotrack settings from the Mixpanel server

@property (nonatomic) BOOL trackAutomaticEventsEnabled

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

  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:flushInterval:. 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:optOutTrackingByDefault:

Initializes a singleton instance of the API, uses it to set whether or not to opt out tracking for GDPR compliance, and then returns it.

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

Parameters

apiToken

your project token

optOutTrackingByDefault

whether or not to be opted out from tracking by default

Discussion

With the optOutTrackingByDefault parameter, Mixpanel tracking can be opted out by default.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:trackCrashes:

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

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

Parameters

apiToken

your project token

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

With the trackCrashes parameter, Mixpanel can track crashes.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:useUniqueDistinctId:

Initializes a singleton instance of the API, using the unique device identifier for distinct_id and then returns it.

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

Parameters

apiToken

your project token

useUniqueDistinctId

whether or not to use the unique device identifier as the distinct_id

Discussion

With the useUniqueDistinctId parameter, Mixpanel will use a unique device id for distinct_id.

Declared In

Mixpanel.h

+ sharedInstanceWithToken:trackCrashes:optOutTrackingByDefault:useUniqueDistinctId:

Initializes a singleton instance of the API, uses it to track crashes, set whether or not to opt out tracking for GDPR compliance, and then returns it.

+ (Mixpanel *)sharedInstanceWithToken:(NSString *)apiToken trackCrashes:(BOOL)trackCrashes optOutTrackingByDefault:(BOOL)optOutTrackingByDefault useUniqueDistinctId:(BOOL)useUniqueDistinctId

Parameters

apiToken

your project token

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

optOutTrackingByDefault

whether or not to be opted out from tracking by default

useUniqueDistinctId

whether or not to use the unique device identifier as the distinct_id

Discussion

With the optOutTrackingByDefault parameter, Mixpanel tracking can be opted out by default.

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:flushInterval 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:flushInterval:.

Declared In

Mixpanel.h

– initWithToken:flushInterval:trackCrashes:useUniqueDistinctId:

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 flushInterval:(NSUInteger)flushInterval trackCrashes:(BOOL)trackCrashes useUniqueDistinctId:(BOOL)useUniqueDistinctId

Parameters

apiToken

your project token

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

useUniqueDistinctId

whether or not to use the unique device identifier as the distinct_id

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. This also sets it as a shared instance so you can use sharedInstance or sharedInstanceWithToken: to retrieve this object later.

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

Parameters

apiToken

your project token

flushInterval

interval to run background flushing

Discussion

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

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

Mixpanel uses a randomly generated persistent UUID as the default local distinct ID.

If you want to use a unique persistent UUID, you can define the MIXPANEL_UNIQUE_DISTINCT_ID preprocessor flag in your build settings. It then uses the IFV String (UIDevice.current().identifierForVendor) as the default local 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 we are unable to get an IFV, we will fall back to generating a random persistent UUID.

For tracking events, you do not need to call identify:. However, Mixpanel User profiles always require 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

– addGroup:groupID:

Add a group to this user’s membership for a particular group key. The groupKey must be an NSString. The groupID should be a legal MixpanelType value.

- (void)addGroup:(NSString *)groupKey groupID:(id<MixpanelType>)groupID

Parameters

groupKey

the group key

groupID

the group ID

Declared In

Mixpanel.h

– removeGroup:groupID:

Remove a group from this user’s membership for a particular group key. The groupKey must be an NSString. The groupID should be a legal MixpanelType value.

- (void)removeGroup:(NSString *)groupKey groupID:(id<MixpanelType>)groupID

Parameters

groupKey

the group key

groupID

the group ID

Declared In

Mixpanel.h

– setGroup:groupIDs:

Set the group to which the user belongs. The groupKey must be an NSString. The groupID should be an array of MixpanelTypes.

- (void)setGroup:(NSString *)groupKey groupIDs:(NSArray<id<MixpanelType> > *)groupIDs

Parameters

groupKey

the group key

groupIDs

the group IDs

Declared In

Mixpanel.h

– setGroup:groupID:

Convenience method to set a single group ID for the current user.

- (void)setGroup:(NSString *)groupKey groupID:(id<MixpanelType>)groupID

Parameters

groupKey

the group key

groupID

the group ID

Declared In

Mixpanel.h

– trackWithGroups:properties:groups:

Tracks an event with specific groups.

- (void)trackWithGroups:(NSString *)event properties:(NSDictionary *)properties groups:(NSDictionary *)groups

Parameters

event

event name

properties

properties dictionary

groups

groups dictionary, which contains key-value pairs for this event

Discussion

Similar to track(), the data will also be sent to the specific group datasets. Group key/value pairs are upserted into the property map before tracking. The keys in groups must be NSString objects. values can be any legal MixpanelType objects. If the event is being timed, the timer will stop and be added as a property.

Declared In

Mixpanel.h

– getGroup:groupID:

Get a MixpanelGroup identifier from groupKey and groupID. The groupKey must be an NSString. The groupID should be a legal MixpanelType value.

- (MixpanelGroup *)getGroup:(NSString *)groupKey groupID:(id<MixpanelType>)groupID

Parameters

groupKey

the group key

groupID

the group ID

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

– clearTimedEvent:

Clears the event timer for the named event.

- (void)clearTimedEvent:(NSString *)event

Parameters

event

the name of the event to clear the timer for

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.

Declared In

Mixpanel.h

– archive

Writes current project info, including distinct ID, super properties 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:

The alias method creates an alias which Mixpanel will use to remap one id to another. Multiple aliases can point to the same identifier.

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

Parameters

alias

A unique identifier that you want to use as an identifier for this user.

distinctID

The current user identifier.

Discussion

[mixpanel createAlias:@"New ID"
         forDistinctID:mixpanel.distinctId];

// You can add multiple id aliases to the existing id
[mixpanel createAlias:@"Newer ID"
         forDistinctID: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

– optOutTracking

Opt out tracking.

- (void)optOutTracking

Discussion

This method is used to opt out tracking. This causes all events and people request no longer to be sent back to the Mixpanel server.

Declared In

Mixpanel.h

– optInTracking

Opt in tracking.

- (void)optInTracking

Discussion

Use this method to opt in an already opted out user from tracking. People updates and track calls will be sent to Mixpanel after using this method.

This method will internally track an opt in event to your project. If you want to identify the opt-in event and/or pass properties to the event, See also optInTrackingForDistinctId: and optInTrackingForDistinctId:withEventProperties:.

Declared In

Mixpanel.h

– optInTrackingForDistinctID:

Opt in tracking.

- (void)optInTrackingForDistinctID:(nullable NSString *)distinctID

Parameters

distinctID

optional string to use as the distinct ID for events. This will call identify:. If you use people profiles make sure you manually call identify: after this method.

Discussion

Use this method to opt in an already opted out user from tracking. People updates and track calls will be sent to Mixpanel after using this method.

This method will internally track an opt in event to your project. If you want to pass properties to the event, see also optInTrackingForDistinctId:withEventProperties:.

Declared In

Mixpanel.h

– optInTrackingForDistinctID:withEventProperties:

Opt in tracking.

- (void)optInTrackingForDistinctID:(nullable NSString *)distinctID withEventProperties:(nullable NSDictionary *)properties

Parameters

distinctID

optional string to use as the distinct ID for events. This will call identify:. If you use people profiles make sure you manually call identify: after this method.

properties

optional properties dictionary that could be passed to add properties to the opt-in event that is sent to Mixpanel.

Discussion

Use this method to opt in an already opted out user from tracking. People updates and track calls will be sent to Mixpanel after using this method.

This method will internally track an opt in event to your project.See also optInTracking or optInTrackingForDistinctId:.

Declared In

Mixpanel.h

– hasOptedOutTracking

Returns YES if the current user has opted out tracking, NO if the current user has opted in tracking.

- (BOOL)hasOptedOutTracking

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