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.getInstance().logEvent("Food Order", EventType.Transaction);

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.

Map<String, String> eventInfo = new HashMap<String, String>(2);
eventInfo.put("spice", "hot");
eventInfo.put("menu", "weekdays");

MPEvent event = new MPEvent.Builder("Food Order", EventType.Transaction)
                .duration(100)
                .info(eventInfo)
                .category("Delivery")
                .build();

MParticle.getInstance().logEvent(event);
MPEvent.Builder("Food Order", MParticle.EventType.Transaction).run {
    duration(100.0)
    HashMap<String, String>(2).apply {
        put("spice", "hot")
        put("menu", "weekdays")
    }.let {
        info(it)
    }
    category("Delivery")
    build()
}.also {
    MParticle.getInstance().logEvent(it)
}

Timed Events

You can additionally use the SDK to track the duration of an 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.

MPEvent.Builder eventBuilder = null;

private void levelStarted() {
   eventBuilder = new MPEvent.Builder("level_completed", EventType.Other)
   .startTime();
   //you can also store MPEvent.Builder objects in persistence, to retrieve them across sessions and app-restarts:
   sharedPreferences("level_completed_event", eventBuilder.toString());
}

private void levelCompleted(){
  //if the app has been restarted, and you've persisted the event builder
  if (eventBuilder == null){
     eventBuilder = MPEvent.Builder.parseString(sharedPreferences.getString("level_completed_event"));
  }
  eventBuilder.endTime();
  MParticle.getInstance().logEvent(eventBuilder.build());
}
var eventBuilder : MPEvent.Builder? = null

private fun levelStarted() {
    eventBuilder = MPEvent.Builder("level_completed", MParticle.EventType.Other)
        .startTime();
    //you can also store MPEvent.Builder objects in persistence, to retrieve them across sessions and app-restarts:
    sharedPreferences("level_completed_event", eventBuilder.toString());
}

private fun levelCompleted() {
    //if the app has been restarted, and you've persisted the event builder
    eventBuilder = eventBuilder ?: MPEvent.Builder.parseString(sharedPreferences.getString("level_completed_event"))
    eventBuilder?.also {
        it.endTime()
        MParticle.getInstance().logEvent(it.build())
    }
}

Event Type

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

public enum EventType {
        Unknown,
        Navigation,
        Location,
        Search,
        Transaction,
        UserContent,
        UserPreference,
        Social,
        Other;
}
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 = new MPEvent.Builder("Set Interest", MParticle.EventType.UserPreference)
                .addCustomFlag("Lotame.Interest", "top-40-music")
                .build();
MParticle.getInstance().logEvent(event);
MPEvent.Builder("Set Interest", MParticle.EventType.UserPreference).run {
    addCustomFlag("Lotame.Interest", "top-40-music")
    build()
}.also {
    MParticle.getInstance().logEvent(it)
}

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.getInstance().upload();

In all other cases, mParticle uploads events at a configurable interval

//set upload interval in seconds
MParticle.getInstance().setUploadInterval(30);