Insert custom events and attributes to New Relic Mobile data

New Relic Mobile sends some default event data from your mobile app to New Relic Insights, such as data about interactions, sessions, crashes, and request errors. You can also create your own custom attributes and events for more detailed analysis in Insights.

For an explanation of all Mobile custom data types, see Add custom data to New Relic Mobile.

Events and attributes

In New Relic products, an event is a grouping of attributes (key-value pairs) that New Relic creates, based on user interactions and other activity in your application. These events are sent to New Relic and can be queried and analyzed in New Relic Insights.

Mobile event types created by default include:

  • Mobile
  • MobileSession
  • MobileCrash
  • MobileRequestError
  • MobileRequest

To see the attribute data associated with an event, use the Insights Data explorer.

Create custom attributes and events

You can create custom session-level attributes for default Mobile events using the New Relic Mobile SDK. For example, to record a username attribute for some part of your iOS or Android app, you would use the setAttribute API (Android | iOS). These attributes are session-related information and are shared by multiple Mobile event types.

You can also create entirely new custom event types and assign them their own custom attributes, using the recordCustomEvent API (Android | iOS).

To help with crash analysis, you can use the SDK to create MobileBreadcrumb & MobileHandledException events. These events are available in Insights and also in the Mobile crash event trail.

For more on creating custom attributes and custom events, see:

As of Android agent version 5.12.0 and iOS agent version 5.12.0, use the recordCustomEvent method to create custom events. The recordEvent methods for Android and iOS are deprecated.

The deprecated recordEvent events do not have their own event type; they are recorded as a Mobile event type with a category attribute value of custom. recordCustomEvent creates an event with an eventType you can assign. But the eventType should only be used for one or two high-level event types, not for naming events. For example, you might have one event type Gestures, with many different names under that one type. For more context on this, see the recordCustomEvent query example.

Mobile event and attribute query examples

Here are some examples of using New Relic Insights to query your mobile app events and attributes:

Custom event example: Track purchases

To track purchases in your app, use recordCustomEvent to create an event type (such as "UserAction") and associate attributes such as "name" (with value "Purchase"), price, quantity, and SKU.

For performance reasons, you should limit the total number of event types to maybe one or two. The recordCustomEvent parameter eventType is meant to be used for high-level categories. For example, you might create an event typeGestures, and then create many different custom event names under the Gesture event type.

Create an event on iOS:

BOOL purchaseRecorded = [NewRelic recordCustomEvent:@"UserAction" attributes:@{@"name": @"Purchase", @"sku": @"12345LPD", @"quantity": @1, @"unitPrice": @99.99, @"total": @99.99}];

Create an event on Android:

Map<String, Object> userActionAttributes = new HashMap<String, Object>();

userActionAttributes.put("name", "Purchase"); 

userActionAttributes.put("sku", "12345LPD");

userActionAttributes.put("quantity", 1);

userActionAttributes.put("unitPrice", 99.99);

userActionAttributes.put("total", 99.99);

boolean userActionRecorded = NewRelic.recordCustomEvent("UserAction", userActionAttributes);

Insights then records a custom event of type UserAction and name Purchase, which allows you to query all purchases made in your app in the last day:

SELECT * from UserAction where name = 'Purchase' since 1 day ago

Replace deprecated recordEvent method:

As of Android agent version 5.12.0 and iOS agent version 5.12.0, use the recordCustomEvent method to create these custom events. If you have replaced the deprecated recordEvent method for your custom events, be sure to also replace its corresponding NRQL query with the new format.

Look for queries used with recordEvent method, such as this:

SELECT * from Mobile where category = 'Custom' and name = 'Purchase' since 1 day ago

Replace them with the query format used with recordCustomEvent:

SELECT * from UserAction where name = 'Purchase' since 1 day ago
Attribute example: Track a specific user

You can create a custom attribute to track a custom user identifier across the session, and then query for all that user's interactions. To add an attribute for the userId, call the setUserId method:

Set the userId on iOS:

BOOL userIdWasSet = [NewRelic setUserId:@"jsmith"];

Set the userId on Android:

boolean userIdWasSet = NewRelic.setUserId("jsmith");

With this attribute, you can use a WHERE clause to see all actions performed by that username in the last day:

SELECT * from Mobile WHERE userId = 'jsmith' since 1 day ago
Attribute example: Track a specific store id

You can create a custom attribute to track a store id across the session, and then query for all that store's interactions. To add an attribute for the storeId, call the setAttribute method:

Set the storeId on iOS:

BOOL attributeSet = [NewRelic setAttribute:@"storeId" value:@"NY0531"];

Set the storeId on Android:

boolean attributeSet = NewRelic.setAttribute("storeId", "NY0531");

With this attribute, you can use a WHERE clause to see all actions performed by that storeId in the last day:

SELECT * from Mobile WHERE storeId = 'NY0531' since 1 day ago
Custom attribute example: Track a specific action

You can use custom attributes to track the number of times that a specific action occurs in your application. For example, you can track the number of times a button was clicked or the number of times a level was completed in a game.

To track completing a game level, call incrementAttribute with no value specified. This creates an attribute with a default value of 1:

Create a counter on iOS:

BOOL levelIncremented = [NewRelic incrementAttribute@"level"];

Create a counter on Android:

boolean levelIncremented = NewRelic.incrementAttribute("level");

Each subsequent call to incrementAttribute adds 1 to the attribute level:

Increment a counter on iOS:

levelIncremented = [NewRelic incrementAttribute@"level"];

Increment a counter on Android:

levelIncremented = NewRelic.incrementAttribute("level");

Be sure to reset the value to 0 when starting over.

To reset the level back to 1 or 0, call setAttribute:

Reset a counter on iOS:

levelReset = [NewRelic setAttribute:@"level" value:@1];

Reset a counter on Android:

levelReset = NewRelic.setAttribute("level", 1);

Then in Insights, use this level attribute to filter your data. For example, if you have a username and level attribute, use the max() function to find the highest level the user had reached:

SELECT max(level) from Mobile where username = 'jsmith'

Size limits and restricted characters

Limits for custom attributes added to default Mobile events:

  • Attributes: 128 maximum
  • String attributes: 4 KB maximum length

Limits for custom events:

  • Attributes: 254 maximum per event (number includes default session attributes)
  • String attributes: 4 KB maximum length

Naming syntax and rules: See Insights rules for custom data.

Set the time to send data

By default, New Relic transmits event data in any of these situations:

  • A session has been ongoing for 600 seconds.
  • The app session ends by backgrounding.
  • The app crashes.

If the app crashes, New Relic gathers the attributes and events for that session and sends them to Insights. (On iOS, this happens the next time the app is launched). You can then use Insights to query and analyze the event and attribute data.

To set the maximum time (in seconds) that the agent will store events in memory, use the following SDK calls:

  • iOS method:

    + (void) setMaxEventBufferTime:(unsigned int)seconds;
  • Android method:

    public static void setMaxEventBufferTime(int maxBufferTimeInSec);

For more help

Additional documentation resources include:

Recommendations for learning more: