Event Tracking

Events can represent any generic activity in your application that you think might be worth tracking. Examples could be tapping a button, finishing a game level - really any user interaction that you may want to track and analyze. Special event types such as screen views, eCommerce transactions, and errors are covered later in this guide.

Events are logged using the logEvent method and/or one of its variants.

[[MParticle sharedInstance] logEvent:@"Food order"
                           eventType:MPEventTypeTransaction];
MParticle.sharedInstance().logEvent("Food order", eventType: MPEventType.transaction, eventInfo: nil)

MPEvent

MPEvent describes an event and all of its properties. It also gives you the ability to keep a reference to an event whose lifespan is longer than the execution of the current block of code. You use MPEvent in conjunction with the logEvent method. Create an instance of MPEvent, populate it with all the data you want to log for a particular event, then pass it as a parameter to logEvent. All properties are optional with the exception of a name and an event type.

MPEvent *event = [[MPEvent alloc] initWithName:@"Food Order"
                                          type:MPEventTypeTransaction];

event.info = @{@"spice":@"hot",
               @"menu":@"weekdays"}; // optional

event.duration = @(100); // in seconds (optional)
event.category = @"Delivery"; // optional

[[MParticle sharedInstance] logEvent:event];
let event = MPEvent(name: "Food Order", type: MPEventType.transaction)

event?.info = ["spice": "hot", "menu": "weekdays"]; // optional

event?.duration = 100 // in seconds (optional)
event?.category = "Delivery" // optional

if (event != nil) {
    MParticle.sharedInstance().logEvent(event!)
}

Timed Events

You can additionally use the SDK to track the duration of an event.

- (void)downloadButtonTapped:(id)sender {
    MPEvent *event = [[MPEvent alloc] initWithName:@"Downloading resource"
                                              type:MPEventTypeOther];

    event.info = @{@"resource_type":@"image",
                   @"resource_name":"outer_space_bg.png"};

    [[MParticle sharedInstance] beginTimedEvent:event];

    // ... execute asynchronous code
}

- (void)resourceDidFinishDownloading {
    MParticle *mParticle = [MParticle sharedInstance];

    MPEvent *event = [mParticle eventWithName:@"Downloading resource"];
    [mParticle endTimedEvent:event];
}
func downloadButtonTapped(sender: Any) {
    let event = MPEvent(name: "Downloading resource", type: MPEventType.other)
    
    event?.info = ["resource_type": "image", "resource_name": "outer_space_bg.png"]; // optional
    
    if (event != nil) {
        MParticle.sharedInstance().beginTimedEvent(event!)
    }
    
    // ... execute asynchronous code
}

func resourceDidFinishDownloading() {
    let event = MParticle.sharedInstance().event(withName: "Downloading resource")
    if (event != nil) {
        MParticle.sharedInstance().endTimedEvent(event!)
    }
}

To make things easier, iOS and tvOS mParticle SDK will maintain timed events for you. Start by creating an instance of MPEvent and pass it as an argument to beginTimedEvent. You don’t need to keep a reference to the MPEvent object, the mParticle SDK keeps the object referenced for you. When you need to retrieve a reference to that object just use the eventWithName method. Once you have the reference to the MPEvent object you can call either endTimedEvent or logEvent to end timing the event and effectively log the event.

In order to start timing an event with the SDK, create an MPEvent.Builder object and call startTime() on it. Later, call endTime() and then log the event as you would normally with logEvent.

Event Type

The SDK provides an enumeration that represents the possible event types. See below for a description of this categorization.

typedef NS_ENUM(NSUInteger, MPEventType) {
    MPEventTypeNavigation = 1,  
    MPEventTypeLocation,      
    MPEventTypeSearch,       
    MPEventTypeTransaction,    
    MPEventTypeUserContent,      
    MPEventTypeUserPreference,  
    MPEventTypeSocial,          
    MPEventTypeOther            
};
Event Type Description
Navigation Events that indicate a user click sequence or content consumption. Examples might include interface navigation, music listening, video view, menu or tab selection, or when the back button is pressed.
Location Events that indicate where a user is located or interacting physically. Examples might include a check-in, geo fence, or GPS navigation.
Search Any event where users input criteria to find content/answers. Examples might include a keyword search, voice search, or a QR code scan.
Transaction Any events that are part of a transaction workflow. Examples might include selecting a product, subscribe, upgrade, or bid.
User content Events where users are creating content. Examples might include create task, compose, record, scan, or save.
User preference Any event that creates personalization for the user. This includes registration, saving/labeling content items, creating profiles, setting application preferences or permissions.
Social Any action where users share content with others. Examples might include post, rate, tweet, share, attach, email.
Other Use this event type to create an event that falls into no clear category.

Custom Flags

Custom flags are used to trigger specific behavior and send specific data-points to particular providers. By design, custom flags are sent only to the specific provider for which they are required. This differs from generic, custom event attributes, which mParticle will send to all of your configured services which support generic key/value event data. Custom Flags cannot be used within an audience definition.

Reference the guide for each integration to see if you need to instrument custom flags.

MPEvent *event = [[MPEvent alloc] initWithName:@"Set Interest"
                                          type:MPEventTypeUserPreference;

[event addCustomFlag:@"top-40-music"
             withKey:@"Lotame.Interest"];

[[MParticle sharedInstance] logEvent:event];
let event = MPEvent(name: "Set Interest", type: MPEventType.userPreference)

event?.addCustomFlag("top-40-music", withKey: "Lotame.Interest")

if (event != nil) {
    MParticle.sharedInstance().logEvent(event!)
}

Upload Frequency

To save bandwidth, mParticle does not always immediately send each event as it is generated. Instead we upload batches of events according to the following rules:

The SDK always uploads as soon as possible on the first session for a client, to ensure that install events are immediately available.

Whenever a Commerce event is logged, mParticle will imediately upload all queued events.

mParticle uploads all queued events whenever a session ends. This may be after a user navigates away from your app according to the configured session timeout

You can force an upload with the upload method:

[[MParticle sharedInstance] upload];
MParticle.sharedInstance().upload()

In all other cases, mParticle uploads events at a set interval. Default times are 10 seconds in development, 10 minutes in production, but can be configured with the setUploadInterval method:

//set upload interval in seconds
[[MParticle sharedInstance] setUploadInterval:30];
MParticle.sharedInstance().uploadInterval = 30