---
title: Report mobile monitoring custom events and attributes
source: https://docs.newrelic.com/docs/data-apis/custom-data/custom-events/report-mobile-monitoring-custom-events-attributes
---

By default, New Relic collects some [event data](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-default-events-insights) from your mobile app to New Relic, such as interactions, sessions, crashes, and request errors. However, you can also create your own custom attributes and events for more detailed querying and analysis.

## Create custom attributes and events [#custom-attributes-instructions]

You can create custom session-level attributes for default mobile monitoring events using the mobile agent SDK. For example, to record a `username` attribute for some part of your iOS or Android app, you would use the [`setAttribute` API](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute). 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](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events).

To help with crash analysis, you can use the SDK to create `MobileBreadcrumb` and `MobileHandledException` events. These events are available for querying and also displayed in the [crash event trail UI](https://docs.newrelic.com/docs/mobile-monitoring/mobile-monitoring-ui/crashes/mobile-crash-event-trail).

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

-   [Mobile SDK guide](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/mobile-sdk-api-guide)
-   [NRQL query examples](#examples)
-   [`MobileRequestError` examples](https://docs.newrelic.com/docs/insights/nrql-new-relic-query-language/nrql-query-examples/mobile-request-failures-query-examples-mobilerequesterror)
-   [`MobileRequest` examples](https://docs.newrelic.com/docs/insights/insights-data-sources/default-attributes/mobile-request-query-examples-mobilerequest)
-   [Limits and restricted characters](#limits)

## Mobile event and attribute query examples [#examples]

Here are some examples of using [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql) 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.

> #### 💡 TIP
>
> 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 type`Gestures`, and then create many different custom event names under the `Gesture` event type.

**Create an event on iOS:**

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

<DNT>
  **Create an event on Android:**
</DNT>

```java
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);
```

New Relic reports a custom event of type `UserAction` and name `Purchase`, which allows you to query all purchases made in your app in the last day:

```sql
SELECT * FROM UserAction WHERE name = 'Purchase' SINCE 1 day ago
```

<DNT>
  **Replace deprecated `recordEvent` method:**
</DNT>

As of [Android agent version 5.12.0](/docs/release-notes/mobile-release-notes/android-release-notes) and [iOS agent version 5.12.0](/docs/release-notes/mobile-release-notes/ios-release-notes), 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:

```sql
SELECT * FROM Mobile WHERE category = 'Custom' AND name = 'Purchase' SINCE 1 day ago
```

Replace them with the query format used with `recordCustomEvent`:

```sql
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:**

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

<DNT>
  **Set the `userId` on Android:**
</DNT>

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

With this attribute, you can use a [`WHERE`](/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-where) clause to see all actions performed by that `username` in the last day:

```sql
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:**

````objectivec
BOOL attributeSet = [NewRelic <a href="/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/">setAttribute</a>:@"storeId" value:@"NY0531"];
```

<DNT>
  **Set the `storeId` on Android:**
</DNT>

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

With this attribute, you can use a [`WHERE`](/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#sel-where) clause to see all actions performed by that `storeId` in the last day:

```sql
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:**

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

<DNT>
  **Create a counter on Android:**
</DNT>

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

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

<DNT>
  **Increment a counter on iOS:**
</DNT>

```objectivec
levelIncremented = [NewRelic incrementAttribute@"level"];
```

<DNT>
  **Increment a counter on Android:**
</DNT>

```java
levelIncremented = NewRelic.incrementAttribute("level");
```

<Callout variant="important">
  Be sure to reset the value to 0 when starting over.
</Callout>

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

<DNT>
  **Reset a counter on iOS:**
</DNT>

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

<DNT>
  **Reset a counter on Android:**
</DNT>

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

When querying, use this `level` attribute to filter your data. For example, if you have a `username` and `level` attribute, use the [`max()`](/docs/insights/new-relic-insights/using-new-relic-query-language/nrql-reference#func-max) function to find the highest level the user had reached:

```sql
SELECT max(level) FROM Mobile WHERE username = 'jsmith'
```

````

## Size limits and restricted characters [#limits]

Limits for [custom attributes added to default mobile events](#event-definition):

-   Attributes: 128 maximum
-   String attributes: 4 KB maximum length (empty string values are not accepted)

Limits for custom events:

-   Attributes: 254 maximum per event (number includes default [session attributes](https://docs.newrelic.com/docs/insights/insights-data-sources/default-data/mobile-default-event-attributes-insights#session-list))
-   String attributes: 4 KB maximum length (empty string values are not accepted)

Naming syntax and rules: See [Rules for custom data](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-data/data-requirements#general).

## Set the time to send data [#data-timing]

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

-   A session has been ongoing for 60 seconds.
-   The app session ends by backgrounding.
-   The app crashes.

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

To set the maximum time (in seconds) that the agent will store events in memory, see [Set max buffer time](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/set-max-event-buffer-time).

## Privacy considerations [#data-privacy]

If you want to collect personal data via custom attributes, please consult with your privacy or legal teams. Be sure to follow your organization's obligations for notices and consent regulations.