MParticle Class Reference

Inherits from NSObject
Declared in mParticle.h

Overview

This is the main class of the mParticle SDK. It interfaces your app with the mParticle API so you can report and measure the many different metrics of your app.

Usage:

Swift


let mParticle = MParticle.sharedInstance()

Objective-C


MParticle *mParticle = [MParticle sharedInstance];

  identity

This property is an instance of MPIdentityApi. It allows tracking login, logout, and identity changes.

@property (nonatomic, strong, readonly) MPIdentityApi *identity

Discussion

This property is an instance of MPIdentityApi. It allows tracking login, logout, and identity changes.

Declared In

mParticle.h

  )

If set to YES development logs will be output to the console, if set to NO the development logs will be suppressed. This property works in conjunction with the environment property. If the environment is Production, consoleLogging will always be NO, regardless of the value you assign to it.

@property (nonatomic, unsafe_unretained, readonly) BOOL consoleLogging DEPRECATED_MSG_ATTRIBUTE ( "set logLevel on MParticleOptions instead" )

Discussion

If set to YES development logs will be output to the console, if set to NO the development logs will be suppressed. This property works in conjunction with the environment property. If the environment is Production, consoleLogging will always be NO, regardless of the value you assign to it.

Declared In

mParticle.h

  environment

The environment property returns the running SDK environment: Development or Production.

@property (nonatomic, unsafe_unretained, readonly) MPEnvironment environment

Discussion

The environment property returns the running SDK environment: Development or Production.

Declared In

mParticle.h

  initialized

Flag indicating whether the mParticle SDK has been fully initialized yet or not. You can KVO this property to know when the SDK successfully finishes initializing

@property (nonatomic, unsafe_unretained, readonly) BOOL initialized

Discussion

Flag indicating whether the mParticle SDK has been fully initialized yet or not. You can KVO this property to know when the SDK successfully finishes initializing

Declared In

mParticle.h

  logLevel

Specifies the log level output to the console while the app is under development: none, error, warning, and debug. When the environment is Production, the log level will always be none, regardless of the value you assign to it.

@property (nonatomic, unsafe_unretained) MPILogLevel logLevel

Discussion

Specifies the log level output to the console while the app is under development: none, error, warning, and debug. When the environment is Production, the log level will always be none, regardless of the value you assign to it.

Declared In

mParticle.h

  optOut

Gets/Sets the opt-in/opt-out status for the application. Set it to YES to opt-out of event tracking. Set it to NO to opt-in of event tracking. The default value is NO (opt-in of event tracking)

@property (nonatomic, unsafe_unretained, readwrite) BOOL optOut

Discussion

Gets/Sets the opt-in/opt-out status for the application. Set it to YES to opt-out of event tracking. Set it to NO to opt-in of event tracking. The default value is NO (opt-in of event tracking)

Declared In

mParticle.h

  proxiedAppDelegate

A flag indicating whether the mParticle Apple SDK has proxied the App Delegate and is handling application notifications automatically.

@property (nonatomic, unsafe_unretained, readonly) BOOL proxiedAppDelegate

Discussion

A flag indicating whether the mParticle Apple SDK has proxied the App Delegate and is handling application notifications automatically.

Declared In

mParticle.h

  automaticSessionTracking

A flag indicating whether the mParticle Apple SDK is using automated Session tracking.

@property (nonatomic, unsafe_unretained, readonly) BOOL automaticSessionTracking

Discussion

A flag indicating whether the mParticle Apple SDK is using automated Session tracking.

Declared In

mParticle.h

  shouldBeginSession

A flag indicating whether the SDK should start a session on SDK init. (Defaults to YES.)

@property (nonatomic, unsafe_unretained, readwrite) BOOL shouldBeginSession

Discussion

A flag indicating whether the SDK should start a session on SDK init. (Defaults to YES.)

See Also

Declared In

mParticle.h

  currentSession

The current session. You can access properties for Session ID and UUID.

@property (atomic, strong, nullable, readonly) MParticleSession *currentSession

Discussion

The current session. You can access properties for Session ID and UUID.

Declared In

mParticle.h

  customUserAgent

Gets/Sets the user agent to a custom value.

@property (atomic, strong, nullable, readonly) NSString *customUserAgent

Discussion

Gets/Sets the user agent to a custom value.

Declared In

mParticle.h

  collectUserAgent

Determines whether the mParticle Apple SDK will instantiate a webview in order to collect the browser user agent. This value is required by attribution providers for fingerprint identification, when device IDs are not available. If you disable this flag, consider populating the user agent via the customUserAgent property above if you are using an attribution provider (such as Kochava or Tune) via mParticle. Defaults to YES

@property (atomic, unsafe_unretained, readonly) BOOL collectUserAgent

Discussion

Determines whether the mParticle Apple SDK will instantiate a webview in order to collect the browser user agent. This value is required by attribution providers for fingerprint identification, when device IDs are not available. If you disable this flag, consider populating the user agent via the customUserAgent property above if you are using an attribution provider (such as Kochava or Tune) via mParticle. Defaults to YES

Declared In

mParticle.h

  networkOptions

Allows you to proxy SDK traffic by overriding the default network endpoints and certificates used by the SDK.

@property (nonatomic, readonly) MPNetworkOptions *networkOptions

Discussion

Allows you to proxy SDK traffic by overriding the default network endpoints and certificates used by the SDK.

See Also

Declared In

mParticle.h

  pushNotificationToken

Gets/Sets the push notification token for the application.

@property (nonatomic, strong, nullable) NSData *pushNotificationToken

Discussion

Gets/Sets the push notification token for the application.

Declared In

mParticle.h

  trackNotifications

Determines whether the mParticle Apple SDK will automatically track Remote and Local Notification events. Defaults to YES

@property (atomic, unsafe_unretained, readonly) BOOL trackNotifications

Discussion

Determines whether the mParticle Apple SDK will automatically track Remote and Local Notification events. Defaults to YES

Declared In

mParticle.h

  sessionTimeout

Gets the user session timeout interval. A session is ended if the app goes into the background for longer than the session timeout interval or when more than 1000 events are logged.

@property (nonatomic, unsafe_unretained, readonly) NSTimeInterval sessionTimeout

Discussion

Gets the user session timeout interval. A session is ended if the app goes into the background for longer than the session timeout interval or when more than 1000 events are logged.

Declared In

mParticle.h

  uniqueIdentifier

Unique identifier for this app running on this device. This unique identifier is synchronized with the mParticle servers.

@property (nonatomic, strong, readonly, nullable) NSString *uniqueIdentifier

Return Value

A string containing the unique identifier or nil, if communication with the server could not yet be established.

Discussion

Unique identifier for this app running on this device. This unique identifier is synchronized with the mParticle servers.

Declared In

mParticle.h

  uploadInterval

Gets/Sets the interval to upload data to mParticle servers.

@property (nonatomic, unsafe_unretained, readonly) NSTimeInterval uploadInterval

Discussion

Gets/Sets the interval to upload data to mParticle servers.

Batches of data are sent periodically to the mParticle servers at the rate defined by the uploadInterval. Batches are also uploaded when the application is sent to the background or before they are terminated.

Declared In

mParticle.h

  version

mParticle Apple SDK version

@property (nonatomic, strong, readonly) NSString *version

Discussion

mParticle Apple SDK version

Declared In

mParticle.h

  dataPlanId

Data plan id

@property (nonatomic, strong, readonly) NSString *dataPlanId

Discussion

Data plan id

Declared In

mParticle.h

  dataPlanVersion

Data plan version

@property (nonatomic, strong, readonly) NSNumber *dataPlanVersion

Discussion

Data plan version

Declared In

mParticle.h

  dataPlanOptions

Sets data plan options for kit blocking

@property (nonatomic, readonly) MPDataPlanOptions *dataPlanOptions

Discussion

Sets data plan options for kit blocking

See Also

Declared In

mParticle.h

+ sharedInstance

Returns the shared instance object.

+ (instancetype)sharedInstance

Return Value

the Singleton instance of the MParticle class.

Discussion

Returns the shared instance object.

Declared In

mParticle.h

– startWithOptions:

Starts the SDK with your API key and secret and installation type. It is required that you use either this method or start to authorize the SDK before using the other API methods. The apiKey and secret that are passed in to this method will override the api_key and api_secret parameters of the (optional) MParticleConfig.plist.

- (void)startWithOptions:(MParticleOptions *)options

Parameters

options

SDK startup options

Discussion

Starts the SDK with your API key and secret and installation type. It is required that you use either this method or start to authorize the SDK before using the other API methods. The apiKey and secret that are passed in to this method will override the api_key and api_secret parameters of the (optional) MParticleConfig.plist.

Declared In

mParticle.h

– didReceiveRemoteNotification:

Informs the mParticle SDK a remote notification has been received. This method should be called only if proxiedAppDelegate is disabled.

- (void)didReceiveRemoteNotification:(NSDictionary *)userInfo

Parameters

userInfo

A dictionary containing information related to the remote notification

Discussion

Informs the mParticle SDK a remote notification has been received. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– didFailToRegisterForRemoteNotificationsWithError:

Informs the mParticle SDK the push notification service could not complete the registration process. This method should be called only if proxiedAppDelegate is disabled.

- (void)didFailToRegisterForRemoteNotificationsWithError:(nullable NSError *)error

Parameters

error

An NSError object encapsulating the information why registration did not succeed

Discussion

Informs the mParticle SDK the push notification service could not complete the registration process. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– didRegisterForRemoteNotificationsWithDeviceToken:

Informs the mParticle SDK the app successfully registered with the push notification service. This method should be called only if proxiedAppDelegate is disabled.

- (void)didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken

Parameters

deviceToken

A token that identifies the device+App to APNS

Discussion

Informs the mParticle SDK the app successfully registered with the push notification service. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– handleActionWithIdentifier:forRemoteNotification:

Informs the mParticle SDK the app has been activated because the user selected a custom action from the alert panel of a remote notification. This method should be called only if proxiedAppDelegate is disabled.

- (void)handleActionWithIdentifier:(nullable NSString *)identifier forRemoteNotification:(nullable NSDictionary *)userInfo

Parameters

identifier

The identifier associated with the custom action

userInfo

A dictionary that contains information related to the remote notification

Discussion

Informs the mParticle SDK the app has been activated because the user selected a custom action from the alert panel of a remote notification. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– handleActionWithIdentifier:forRemoteNotification:withResponseInfo:

Informs the mParticle SDK the app has been activated because the user selected a custom action from the alert panel of a remote notification. This method should be called only if proxiedAppDelegate is disabled.

- (void)handleActionWithIdentifier:(nullable NSString *)identifier forRemoteNotification:(nullable NSDictionary *)userInfo withResponseInfo:(nonnull NSDictionary *)responseInfo

Parameters

identifier

The identifier associated with the custom action

userInfo

A dictionary that contains information related to the remote notification

responseInfo

The data dictionary sent by the action

Discussion

Informs the mParticle SDK the app has been activated because the user selected a custom action from the alert panel of a remote notification. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– openURL:sourceApplication:annotation:

Informs the mParticle SDK the app has been asked to open a resource identified by a URL. This method should be called only if proxiedAppDelegate is disabled.

- (void)openURL:(NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(nullable id)annotation

Parameters

url

The URL resource to open

sourceApplication

The bundle ID of the requesting app

annotation

A property list object supplied by the source app

Discussion

Informs the mParticle SDK the app has been asked to open a resource identified by a URL. This method should be called only if proxiedAppDelegate is disabled.

Declared In

mParticle.h

– openURL:options:

Informs the mParticle SDK the app has been asked to open a resource identified by a URL. This method should be called only if proxiedAppDelegate is disabled. This method is only available for iOS 9 and above.

- (void)openURL:(NSURL *)url options:(nullable NSDictionary *)options

Parameters

url

The URL resource to open

options

The dictionary of launch options

Discussion

Informs the mParticle SDK the app has been asked to open a resource identified by a URL. This method should be called only if proxiedAppDelegate is disabled. This method is only available for iOS 9 and above.

Declared In

mParticle.h

– continueUserActivity:restorationHandler:

Informs the mParticle SDK the app has been asked to open to continue an NSUserActivity. This method should be called only if proxiedAppDelegate is disabled. This method is only available for iOS 9 and above.

- (BOOL)continueUserActivity:(nonnull NSUserActivity *)userActivity restorationHandler:(void ( ^ _Nonnull ) ( NSArray<id<UIUserActivityRestoring> > *__nullable restorableObjects ))restorationHandler

Parameters

userActivity

The NSUserActivity that caused the app to be opened

restorationHandler

A block to execute if your app creates objects to perform the task.

Discussion

Informs the mParticle SDK the app has been asked to open to continue an NSUserActivity. This method should be called only if proxiedAppDelegate is disabled. This method is only available for iOS 9 and above.

Declared In

mParticle.h

– reset

This method will permanently remove ALL MParticle data from the device, including MParticle UserDefaults and Database, it will also halt any further upload or download behavior that may be prepared

- (void)reset

Discussion

This method will permanently remove ALL MParticle data from the device, including MParticle UserDefaults and Database, it will also halt any further upload or download behavior that may be prepared

If you have any reference to the MParticle instance, you must remove your reference by setting it to “nil”, in order to avoid any unexpected behavior The SDK will be shut down and [MParticle sharedInstance] will return a new instance without apiKey or secretKey. MParticle can be restarted by calling MParticle.startWithOptions

Declared In

mParticle.h

– activeTimedEvents

Contains a collection with all active timed events (timed events that had begun, but not yet ended). You should not keep a separate reference collection containing the events being timed. The mParticle SDK manages the lifecycle of those events.

- (nullable NSSet *)activeTimedEvents

Return Value

A set with all active timed events

Discussion

Contains a collection with all active timed events (timed events that had begun, but not yet ended). You should not keep a separate reference collection containing the events being timed. The mParticle SDK manages the lifecycle of those events.

Declared In

mParticle.h

– beginTimedEvent:

Begins timing an event. There can be many timed events going on at the same time, the only requirement is that each concurrent timed event must have a unique event name. After beginning a timed event you don’t have to keep a reference to the event instance being timed, you can use the eventWithName: method to retrieve it later when ending the timed event.

- (void)beginTimedEvent:(MPEvent *)event

Parameters

event

An instance of MPEvent

Discussion

Begins timing an event. There can be many timed events going on at the same time, the only requirement is that each concurrent timed event must have a unique event name. After beginning a timed event you don’t have to keep a reference to the event instance being timed, you can use the eventWithName: method to retrieve it later when ending the timed event.

See Also

Declared In

mParticle.h

– endTimedEvent:

Ends timing an event and logs its data to the mParticle SDK. If you didn’t keep a reference to the event being timed, you can use the eventWithName: method to retrieve it.

- (void)endTimedEvent:(MPEvent *)event

Parameters

event

An instance of MPEvent

Discussion

Ends timing an event and logs its data to the mParticle SDK. If you didn’t keep a reference to the event being timed, you can use the eventWithName: method to retrieve it.

Declared In

mParticle.h

– eventWithName:

When working with timed events you don’t need to keep a reference to the event being timed. You can use this method to retrieve the event being timed passing the event name as parameter. If an instance of MPEvent, with a matching event name cannot be found, this method will return nil.

- (nullable MPEvent *)eventWithName:(NSString *)eventName

Parameters

eventName

A string with the event name associated with the event being timed

Return Value

An instance of MPEvent, if one could be found, or nil.

Discussion

When working with timed events you don’t need to keep a reference to the event being timed. You can use this method to retrieve the event being timed passing the event name as parameter. If an instance of MPEvent, with a matching event name cannot be found, this method will return nil.

See Also

Declared In

mParticle.h

– logEvent:

Logs an event. This is one of the most fundamental methods of the SDK. You can define all the characteristics of an event in an instance of MPEvent, MPCommerceEvent, or any other subclass of MPBaseEvent and pass that instance to this method to log its data to the mParticle SDK.

- (void)logEvent:(MPBaseEvent *)event

Parameters

event

An instance of a subclass of MPBaseEvent (e.g MPEvent, MPCommerceEvent)

Discussion

Logs an event. This is one of the most fundamental methods of the SDK. You can define all the characteristics of an event in an instance of MPEvent, MPCommerceEvent, or any other subclass of MPBaseEvent and pass that instance to this method to log its data to the mParticle SDK.

Declared In

mParticle.h

– logEvent:eventType:eventInfo:

Logs an event. This is a convenience method for logging simple events; internally it creates an instance of MPEvent and calls logEvent:

- (void)logEvent:(NSString *)eventName eventType:(MPEventType)eventType eventInfo:(nullable NSDictionary<NSString*,id> *)eventInfo

Parameters

eventName

The name of the event to be logged (required not nil.) The string cannot be longer than 255 characters

eventType

An enum value that indicates the type of event to be logged

eventInfo

A dictionary containing further information about the event. This dictionary is limited to 100 key value pairs. Keys must be strings (up to 255 characters) and values can be strings (up to 4096 characters), numbers, booleans, or dates

Discussion

Logs an event. This is a convenience method for logging simple events; internally it creates an instance of MPEvent and calls logEvent:

See Also

Declared In

mParticle.h

– logScreenEvent:

Logs a screen event. You can define all the characteristics of a screen event (name, attributes, etc) in an instance of MPEvent and pass that instance to this method to log its data to the mParticle SDK.

- (void)logScreenEvent:(MPEvent *)event

Parameters

event

An instance of MPEvent

Discussion

Logs a screen event. You can define all the characteristics of a screen event (name, attributes, etc) in an instance of MPEvent and pass that instance to this method to log its data to the mParticle SDK.

See Also

Declared In

mParticle.h

– logScreen:eventInfo:

Logs a screen event. This is a convenience method for logging simple screen events; internally it creates an instance of MPEvent and calls logScreenEvent:

- (void)logScreen:(NSString *)screenName eventInfo:(nullable NSDictionary<NSString*,id> *)eventInfo

Parameters

screenName

The name of the screen to be logged (required not nil and up to 255 characters)

eventInfo

A dictionary containing further information about the screen. This dictionary is limited to 100 key value pairs. Keys must be strings (up to 255 characters) and values can be strings (up to 4096 characters), numbers, booleans, or dates

Discussion

Logs a screen event. This is a convenience method for logging simple screen events; internally it creates an instance of MPEvent and calls logScreenEvent:

Declared In

mParticle.h

– attributionInfo

Convenience method for getting the most recently retrieved attribution info for all kits.

- (nullable NSDictionary<NSNumber*,MPAttributionResult*> *)attributionInfo

Return Value

A dictionary containing the most recent attribution info that was retrieved by each kit

Discussion

Convenience method for getting the most recently retrieved attribution info for all kits.

See Also

Declared In

mParticle.h

– beginUncaughtExceptionLogging

Enables mParticle exception handling to automatically log events on uncaught exceptions.

- (void)beginUncaughtExceptionLogging

Discussion

Enables mParticle exception handling to automatically log events on uncaught exceptions.

Declared In

mParticle.h

– endUncaughtExceptionLogging

Disables mParticle automatic exception handling.

- (void)endUncaughtExceptionLogging

Discussion

Disables mParticle automatic exception handling.

Declared In

mParticle.h

– leaveBreadcrumb:

Leaves a breadcrumb. Breadcrumbs are send together with crash reports to help with debugging.

- (void)leaveBreadcrumb:(NSString *)breadcrumbName

Parameters

breadcrumbName

The name of the breadcrumb (required not nil)

Discussion

Leaves a breadcrumb. Breadcrumbs are send together with crash reports to help with debugging.

Declared In

mParticle.h

– leaveBreadcrumb:eventInfo:

Leaves a breadcrumb. Breadcrumbs are send together with crash reports to help with debugging.

- (void)leaveBreadcrumb:(NSString *)breadcrumbName eventInfo:(nullable NSDictionary<NSString*,id> *)eventInfo

Parameters

breadcrumbName

The name of the breadcrumb (required not nil)

eventInfo

A dictionary containing further information about the breadcrumb

Discussion

Leaves a breadcrumb. Breadcrumbs are send together with crash reports to help with debugging.

Declared In

mParticle.h

– logError:

Logs an error with a message.

- (void)logError:(NSString *)message

Parameters

message

The name of the error to be tracked (required not nil)

Discussion

Logs an error with a message.

Declared In

mParticle.h

– logError:eventInfo:

Logs an error with a message and an attributes dictionary. The eventInfo is limited to 100 key value pairs. The values in eventInfo cannot contain more than 4096 characters.

- (void)logError:(NSString *)message eventInfo:(nullable NSDictionary<NSString*,id> *)eventInfo

Parameters

message

The name of the error event (required not nil)

eventInfo

A dictionary containing further information about the error

Discussion

Logs an error with a message and an attributes dictionary. The eventInfo is limited to 100 key value pairs. The values in eventInfo cannot contain more than 4096 characters.

Declared In

mParticle.h

– logException:

Logs an exception.

- (void)logException:(NSException *)exception

Parameters

exception

The exception which occurred

Discussion

Logs an exception.

Declared In

mParticle.h

– logException:topmostContext:

Logs an exception and a context.

- (void)logException:(NSException *)exception topmostContext:(nullable id)topmostContext

Parameters

exception

The exception which occurred

topmostContext

The topmost context of the app, typically the topmost view controller

Discussion

Logs an exception and a context.

Declared In

mParticle.h

– logCommerceEvent:

Logs a commerce event.

- (void)logCommerceEvent:(MPCommerceEvent *)commerceEvent

Parameters

commerceEvent

An instance of MPCommerceEvent

Discussion

Logs a commerce event.

See Also

Declared In

mParticle.h

– logLTVIncrease:eventName:

Increases the LTV (LifeTime Value) amount of a user.

- (void)logLTVIncrease:(double)increaseAmount eventName:(NSString *)eventName

Parameters

increaseAmount

The amount to be added to LTV

eventName

The name of the event (Optional). If not applicable, pass nil

Discussion

Increases the LTV (LifeTime Value) amount of a user.

Declared In

mParticle.h

– logLTVIncrease:eventName:eventInfo:

Increases the LTV (LifeTime Value) amount of a user.

- (void)logLTVIncrease:(double)increaseAmount eventName:(NSString *)eventName eventInfo:(nullable NSDictionary<NSString*,id> *)eventInfo

Parameters

increaseAmount

The amount to be added to LTV

eventName

The name of the event (Optional). If not applicable, pass nil

eventInfo

A dictionary containing further information about the LTV

Discussion

Increases the LTV (LifeTime Value) amount of a user.

Declared In

mParticle.h

+ registerExtension:

Registers an extension against the code mParticle SDK. Extensions are external code, unknown to the core SDK, which conform to one of more known protocols. They allow the core SDK to function in ways beyond its core functionality.

+ (BOOL)registerExtension:(id<MPExtensionProtocol>)extension

Parameters

extension

An instance of a class conforming to a MPExtensionProtocol specialization

Discussion

Registers an extension against the code mParticle SDK. Extensions are external code, unknown to the core SDK, which conform to one of more known protocols. They allow the core SDK to function in ways beyond its core functionality.

Declared In

mParticle.h

– setIntegrationAttributes:forKit:

Set the integration attributes for a given integration ID.

- (MPKitExecStatus *)setIntegrationAttributes:(NSDictionary<NSString*,NSString*> *)attributes forKit:(NSNumber *)integrationId

Parameters

attributes

a dictionary of attributes that will replace any current attributes. The keys are predefined by mParticle. Please consult with the mParticle docs or your solutions consultant for the correct value. You may also pass a null or empty map here to remove all of the attributes.

integrationId

mParticle integration ID. This may be the ID for a kit, or any mParticle integration.

Discussion

Set the integration attributes for a given integration ID.

Integration attributes are keys and values specific to a given integration. For example, many integrations have their own internal user/device ID. mParticle will store integration attributes for a given device, and will be able to use these values for server-to-server communication to services. This is often useful when used in combination with a server-to-server feed, allowing the feed to be enriched with the necessary integration attributes to be properly forwarded to the given integration.

Note: this action will be performed asynchronously.

See Also

Declared In

mParticle.h

– clearIntegrationAttributesForKit:

Clear the integration attributes for a given integration ID.

- (MPKitExecStatus *)clearIntegrationAttributesForKit:(NSNumber *)integrationId

Parameters

integrationId

mParticle integration ID. This may be the ID for a kit, or any mParticle integration.

Discussion

Clear the integration attributes for a given integration ID.

Integration attributes are keys and values specific to a given integration. For example, many integrations have their own internal user/device ID. mParticle will store integration attributes for a given device, and will be able to use these values for server-to-server communication to services. This is often useful when used in combination with a server-to-server feed, allowing the feed to be enriched with the necessary integration attributes to be properly forwarded to the given integration.

Note: this action will be performed asynchronously.

See Also

Declared In

mParticle.h

– integrationAttributesForKit:

Get the integration attributes for a given integration ID.

- (nullable NSDictionary *)integrationAttributesForKit:(NSNumber *)integrationId

Parameters

integrationId

mParticle integration ID. This may be the ID for a kit, or any mParticle integration.

Discussion

Get the integration attributes for a given integration ID.

Integration attributes are keys and values specific to a given integration. For example, many integrations have their own internal user/device ID. mParticle will store integration attributes for a given device, and will be able to use these values for server-to-server communication to services. This is often useful when used in combination with a server-to-server feed, allowing the feed to be enriched with the necessary integration attributes to be properly forwarded to the given integration.

Note: this will make a direct call to SQLite and should not be called on the main thread.

See Also

Declared In

mParticle.h

– onKitsInitialized:

Allows you to schedule code to run after all kits have been initialized. If kits have already been initialized, your block will be invoked immediately. If not, your block will be copied and the copy will be invoked once kit initialization is finished.

- (void)onKitsInitialized:(void ( ^ ) ( void ))block

Parameters

block

A block to be invoked once kits are initialized

Discussion

Allows you to schedule code to run after all kits have been initialized. If kits have already been initialized, your block will be invoked immediately. If not, your block will be copied and the copy will be invoked once kit initialization is finished.

Declared In

mParticle.h

– isKitActive:

Returns whether a kit is active or not. You can retrieve if a kit has been already initialized and can be used.

- (BOOL)isKitActive:(NSNumber *)integrationId

Parameters

integrationId

An NSNumber representing the kit to be checked

Return Value

Whether the kit is active or not.

Discussion

Returns whether a kit is active or not. You can retrieve if a kit has been already initialized and can be used.

Declared In

mParticle.h

– kitInstance:

Retrieves the internal instance of a kit, for cases where you need to use properties and methods of that kit directly.

- (nullable id const)kitInstance:(NSNumber *)integrationId

Parameters

integrationId

An NSNumber representing the kit to be retrieved

Return Value

The internal instance of the kit, or nil, if the kit is not active

Discussion

Retrieves the internal instance of a kit, for cases where you need to use properties and methods of that kit directly.

This method is only applicable to kits that allocate themselves as an object instance or as a singleton. For the cases where kits are implemented with class methods, you can call those class methods directly

See Also

Declared In

mParticle.h

– kitInstance:completionHandler:

Asynchronously retrieves the internal instance of a kit, for cases where you need to use properties and methods of that kit directly.

- (void)kitInstance:(NSNumber *)kitCode completionHandler:(void ( ^ ) ( id _Nullable kitInstance ))completionHandler

Parameters

kitCode

An NSNumber representing the kit to be retrieved

completionHandler

A block to be called if or when the kit instance becomes available. If the kit never becomes active, the block will never be called. If the kit is class based, the instance will be nil

Discussion

Asynchronously retrieves the internal instance of a kit, for cases where you need to use properties and methods of that kit directly.

This method is only applicable to kits that allocate themselves as an object instance or as a singleton. For the cases where kits are implemented with class methods, you can call those class methods directly

See Also

Declared In

mParticle.h

  backgroundLocationTracking

Enables or disables the inclusion of location information to messages when your app is running on the background. The default value is YES. Setting it to NO will cause the SDK to include location information only when your app is running on the foreground.

@property (nonatomic, unsafe_unretained) BOOL backgroundLocationTracking

Discussion

Enables or disables the inclusion of location information to messages when your app is running on the background. The default value is YES. Setting it to NO will cause the SDK to include location information only when your app is running on the foreground.

Declared In

mParticle.h

  location

Gets/Sets the current location of the active session.

@property (nonatomic, strong, nullable) CLLocation *location

Discussion

Gets/Sets the current location of the active session.

Declared In

mParticle.h

– beginLocationTracking:minDistance:

Begins geographic location tracking.

- (void)beginLocationTracking:(CLLocationAccuracy)accuracy minDistance:(CLLocationDistance)distanceFilter

Parameters

accuracy

The desired accuracy

distanceFilter

The minimum distance (measured in meters) a device must move before an update event is generated.

Discussion

Begins geographic location tracking.

The desired accuracy of the location is determined by a passed in constant for accuracy. Choices are kCLLocationAccuracyBestForNavigation, kCLLocationAccuracyBest, kCLLocationAccuracyNearestTenMeters, kCLLocationAccuracyHundredMeters, kCLLocationAccuracyKilometer, and kCLLocationAccuracyThreeKilometers.

Declared In

mParticle.h

– beginLocationTracking:minDistance:authorizationRequest:

Begins geographic location tracking.

- (void)beginLocationTracking:(CLLocationAccuracy)accuracy minDistance:(CLLocationDistance)distanceFilter authorizationRequest:(MPLocationAuthorizationRequest)authorizationRequest

Parameters

accuracy

The desired accuracy

distanceFilter

The minimum distance (measured in meters) a device must move before an update event is generated.

authorizationRequest

Type of authorization requested to use location services

Discussion

Begins geographic location tracking.

The desired accuracy of the location is determined by a passed in constant for accuracy. Choices are kCLLocationAccuracyBestForNavigation, kCLLocationAccuracyBest, kCLLocationAccuracyNearestTenMeters, kCLLocationAccuracyHundredMeters, kCLLocationAccuracyKilometer, and kCLLocationAccuracyThreeKilometers.

Declared In

mParticle.h

– endLocationTracking

Ends geographic location tracking.

- (void)endLocationTracking

Discussion

Ends geographic location tracking.

Declared In

mParticle.h

– logNetworkPerformance:httpMethod:startTime:duration:bytesSent:bytesReceived:

Allows you to log a network performance measurement independently from the mParticle SDK measurement.

- (void)logNetworkPerformance:(NSString *)urlString httpMethod:(NSString *)httpMethod startTime:(NSTimeInterval)startTime duration:(NSTimeInterval)duration bytesSent:(NSUInteger)bytesSent bytesReceived:(NSUInteger)bytesReceived

Parameters

urlString

The absolute URL being measured

httpMethod

The method used in the network communication (e.g. GET, POST, etc)

startTime

The time when the network communication started measured in seconds since Unix Epoch Time: [[NSDate date] timeIntervalSince1970]

duration

The number of seconds it took for the network communication took to complete

bytesSent

The number of bytes sent

bytesReceived

The number of bytes received

Discussion

Allows you to log a network performance measurement independently from the mParticle SDK measurement.

Declared In

mParticle.h

– incrementSessionAttribute:byValue:

Increments the value of a session attribute by the provided amount. If the key does not exist among the current session attributes, this method will add the key to the session attributes and set the value to the provided amount. If the key already exists and the existing value is not a number, the operation will abort.

- (nullable NSNumber *)incrementSessionAttribute:(NSString *)key byValue:(NSNumber *)value

Parameters

key

The attribute key

value

The increment amount

Return Value

The static value @0

Discussion

Increments the value of a session attribute by the provided amount. If the key does not exist among the current session attributes, this method will add the key to the session attributes and set the value to the provided amount. If the key already exists and the existing value is not a number, the operation will abort.

Note: this method has been changed to be async, return value will always be @0.

Declared In

mParticle.h

– setSessionAttribute:value:

Set a single session attribute. The property will be combined with any existing attributes. There is a 100 count limit to existing session attributes. Passing in a nil value for an existing key will remove the session attribute.

- (void)setSessionAttribute:(NSString *)key value:(nullable id)value

Parameters

key

The attribute key

value

The attribute value

Discussion

Set a single session attribute. The property will be combined with any existing attributes. There is a 100 count limit to existing session attributes. Passing in a nil value for an existing key will remove the session attribute.

Declared In

mParticle.h

– beginSession

Manually begins a new session. Calling this method is a no-op if a session already exists.

- (void)beginSession

Discussion

Manually begins a new session. Calling this method is a no-op if a session already exists.

Declared In

mParticle.h

– endSession

Manually ends the current session. Calling this method is a no-op if no session exists.

- (void)endSession

Discussion

Manually ends the current session. Calling this method is a no-op if no session exists.

Declared In

mParticle.h

– upload

Force uploads queued messages to mParticle.

- (void)upload

Discussion

Force uploads queued messages to mParticle.

Declared In

mParticle.h

– surveyURL:

Returns the survey URL for a given provider.

- (nullable NSString *)surveyURL:(MPSurveyProvider)surveyProvider

Parameters

surveyProvider

The survey provider

Return Value

A string with the URL to the survey

Discussion

Returns the survey URL for a given provider.

See Also

Declared In

mParticle.h

– userNotificationCenter:willPresentNotification:

Informs the mParticle SDK that the app has received a user notification while in the foreground.

- (void)userNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification

Parameters

center

The notification center that received the notification

notification

The notification that is about to be delivered

Discussion

Informs the mParticle SDK that the app has received a user notification while in the foreground.

Declared In

mParticle.h

– userNotificationCenter:didReceiveNotificationResponse:

Informs the mParticle SDK that the user has interacted with a given notification

- (void)userNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response

Parameters

center

The notification center that received the notification

response

The user’s response to the notification

Discussion

Informs the mParticle SDK that the user has interacted with a given notification

Declared In

mParticle.h

– initializeWKWebView:

Create a bridge between the mParticle web SDK and iOS SDK.

- (void)initializeWKWebView:(WKWebView *)webView

Parameters

webView

The web view to be initialized

Discussion

Create a bridge between the mParticle web SDK and iOS SDK.

This API will add a persistent WKScriptMessageHandler to the given WKWebView, signaling to the mParticle web SDK that it should delegate all API calls out to the native iOS SDK, rather than sending API calls directly. Note that this handler will persist across page loads.

Declared In

mParticle.h

– initializeWKWebView:bridgeName:

Create a bridge between the mParticle web SDK and iOS SDK.

- (void)initializeWKWebView:(WKWebView *)webView bridgeName:(nullable NSString *)bridgeName

Parameters

webView

The web view to be initialized

bridgeName

The name of the webview bridge

Discussion

Create a bridge between the mParticle web SDK and iOS SDK.

This API will add a persistent WKScriptMessageHandler to the given WKWebView, signaling to the mParticle web SDK that it should delegate all API calls out to the native iOS SDK, rather than sending API calls directly. Note that this handler will persist across page loads.

Declared In

mParticle.h

– logNotificationReceivedWithUserInfo:

Logs a Notification event for a notification that has been reviewed but not acted upon. This is a convenience method for manually logging Notification events; Set trackNotifications to false on MParticleOptions to disable automatic tracking of Notifications and only set Notification manually:

- (void)logNotificationReceivedWithUserInfo:(nonnull NSDictionary *)userInfo

Discussion

Logs a Notification event for a notification that has been reviewed but not acted upon. This is a convenience method for manually logging Notification events; Set trackNotifications to false on MParticleOptions to disable automatic tracking of Notifications and only set Notification manually:

Declared In

mParticle.h

– logNotificationOpenedWithUserInfo:andActionIdentifier:

Logs a Notification event for a notification that has been reviewed and acted upon. This is a convenience method for manually logging Notification events; Set trackNotifications to false on MParticleOptions to disable automatic tracking of Notifications and only set Notification manually:

- (void)logNotificationOpenedWithUserInfo:(nonnull NSDictionary *)userInfo andActionIdentifier:(nullable NSString *)actionIdentifier

Discussion

Logs a Notification event for a notification that has been reviewed and acted upon. This is a convenience method for manually logging Notification events; Set trackNotifications to false on MParticleOptions to disable automatic tracking of Notifications and only set Notification manually:

Declared In

mParticle.h