Best Practices for Event Measurement API

While the pre-defined app events in the MobileAppTracking™ (MAT) Measurement API should be sufficient for most cases, we recognize that there may be occasions where you need to define your own custom event(s). This document clarifies how our tracking engine handles custom events, particularly if you define a custom event that is already pre-defined by MAT, and/or there is a mismatch between your custom event API call and the event configuration you have setup in the MAT platform/app.

If the API call does not reference a pre-defined event (such as “action=purchase” or “action=login“), then it follows the custom event convention described at Measuring Other Custom Events, where custom event API calls have “conversion” as the action (“action=conversion“).

It is not necessary to pre-configure events in the MAT platform. For pre-defined events, the event type is already set. For custom events, you can simply include a unique “site_event_name” value in your API call. For example:

action=conversion&site_event_name=review_submitted

MAT’s tracking engine will automatically create a corresponding event type based on the “site_event_name” value.

The only time you need to define an event (and its type) in the MAT platform is when you later want to use an API call that references the specific event by event ID or event name, or when you want to change the Type of an existing custom event.

To define an event in MAT:

  1. In the navigation (in the left pane), click Mobile Apps.
  2. On the Mobile Apps page (in the right pane), click the mobile app for which you want to define an event.
  3. On the page for your mobile app, click Add Event as shown in the following screenshot.
  4. In the Add Event dialog box, from the Event Type drop-down list, select Event, provide an event name, and then click Finish as shown in the following screenshot.
  5. On the page for your mobile app, note the Event ID and Name for your custom event as shown in the following screenshot.
  6. Now in your API call, reference the event ID or name as described at Measuring Custom Events.

To change the event type for an existing custom event:

  1. Repeat steps 1 and 2 above.
  2. On the page for your mobile app, click the event for which you want to change the type as shown in the following screenshot.
  3. On the “event name” page, click Edit Details as shown in the following screenshot.
  4. On the Edit Event page, from the Event Type drop-down list, select the new desired event type, and then click Update (at the very bottom) as shown in the following screenshot.

Potential Conflicts

There are two cases where potential conflicts may arise, and both involve mismatched event types:

  • You call a pre-defined event that has already been defined in the MAT platform but the event type you select in the MAT platform does not match the event type in your API call. For example, your API call is “action=purchase” but in MAT you set the event type to “Login
  • You call a custom event and define its event type in the MAT platform, but the event type does not match your API call

You do not need to manually configure pre-defined events in the MAT platform. You should only pre-configure events in the MAT platform when you need to reference a custom event by “site_event_id” or “site_event_name” in your API call.

If our tracking engine cannot match the event type of an API call to an event type defined in the MAT platform, then it looks for a matching “ref” value (derived from “site_event_name“). If a corresponding “ref” value is not found, then the tracking engine automatically defines a new event and type.

For example, you add an event in the MAT platform for the pre-defined “login” event (you select “Login” from the Event Type drop-down list and provide the name “Login“. Then internally, our tracking engine creates a new event with the following properties:

  • site_event_id=1
  • site_event_name=Login
  • event ref=login
  • event type=login

So if your app makes an API call with “action=login“, then our tracking engine finds an event for your app with the event type of “login” and event ref of “login“.

But if you added a second “login” event through the MAT platform (for example, “Login2“), then our tracking engine creates an additional event with the following properties:

  • site_event_id=2
  • site_event_name=Login2
  • event ref=login2
  • event type=login

So if your app makes the same API call with “action=login“, then our tracking engine uses the same event for your app (where event ref matches “login“). Your app would have to call “action=login2” for our tracking engine to use the second event of type “login“.

Or if you only had a single event defined in the MAT platform with the following properties:

  • site_event_id=1
  • site_event_name=Signing In
  • event ref=signingin
  • event type=login

Then for any API call(s) involving “action=login“, our tracking engine still uses this event because the event type = “login” and there are no other login events.

Or if the only event you defined in the MAT platform was:

  • site_event_id=1
  • site_event_name=Purchase
  • event ref=purchase
  • event type=purchase

And your API call included “action=login“, then our tracking engine cannot find a “login” event type or event ref for your app, and it would create a new event of said type and use it instead.

For information about which events to consider measuring, please visit In-App Events: Which Ones You Should be Measuring and Why.

Have a Question? Please contact support@tune.com for technical support.