--- title: Record custom events source: https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/record-custom-events --- ## Android ### Syntax [#syntax] #### Java [#java] ```java NewRelic.recordCustomEvent(string $eventType, [string $eventName,] map $eventAttributes) ``` #### Kotlin [#kotlin] ```kotlin NewRelic.recordCustomEvent( eventType: String?, eventName: String?, eventAttributes: MutableMap? ) ``` ### Description [#description] Records a custom New Relic mobile monitoring event. Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. The event includes a list of attributes, specified as a map. Unlike using [`setAttribute`](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/), adding attributes to a custom event adds them only to that event; they are not session attributes. Important considerations and best practices include: - You should limit the total number of event types to approximately five. `eventType` is meant to be used for high-level categories. For example, you might create an event type `Gestures`. - Do not use `eventType` to name your custom events. Create an attribute to name an event or use the optional `name` parameter. While you can create numerous custom events, it's crucial to limit the number of `eventType`s. - Using the optional `name` parameter has the same effect as adding a `name` key in the `attributes` dictionary. `name` is a keyword used for displaying your events in the New Relic UI. To create a useful `name`, you might combine several attributes (see examples). > #### ⚠️ IMPORTANT > > As of New Relic [Android agent version 5.12.0](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/android-release-notes/android-5120), the `recordEvent` method is deprecated and replaced with `recordCustomEvent`. The `recordEvent` method will continue to work for an unspecified period of time, but if your app contains `recordEvent` methods, New Relic recommends you replace them. > > Updating these methods will affect any NRQL queries and dashboards that use the deprecated event types. Be sure to adjust your NRQL queries and dashboards as needed. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events. Instead, use a custom attribute or the optional `name`. | | `$eventName` | `dictionary` | Optional. A map that includes a list of attributes that further designate subcategories to the `$eventType`. You can create attributes for any event descriptors you think will be useful. To name your custom events, create a `name` attribute or use the `eventName` parameter. Note: Not all object types are supported. See [setAttribute](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute//#parameters) for details on supported types. > #### ⚠️ IMPORTANT > > When setting the key for your custom attributes, be aware that there are [default attributes that cannot be overridden](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/#description). | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Examples [#examples] Here's an example of a basic custom event: #### Java [#java] ```java Map attributes = new HashMap(); attributes.put("attributeName1", "value1"); attributes.put("attributeName1", 2); boolean eventRecorded = NewRelic.recordCustomEvent("eventType", attributes); ``` #### Kotlin [#kotlin] ```kotlin val attributes = mutableMapOf("attributeName1" to "value1", "attributeName1" to 2) val eventRecorded = NewRelic.recordCustomEvent("eventType", attributes) ``` Here's an example of a custom event with several attributes: #### Java [#java] ```java Map attributes = new HashMap(); attributes.put("make", "Ford"); attributes.put("model", "ModelT"); attributes.put("color", "Black"); attributes.put("VIN", "123XYZ"); attributes.put("maxSpeed", 12); NewRelic.recordCustomEvent("Car", attributes); ``` #### Kotlin [#kotlin] ```kotlin val attributes = mutableMapOf() attributes["make"] = "Ford" attributes["model"] = "ModelT" attributes["color"] = "Black" attributes["VIN"] = "123XYZ" attributes["maxSpeed"] = 12 NewRelic.recordCustomEvent("Car", attributes) ``` Here's an example of a custom event using the `name` parameter: #### Java [#java] ```java Map attributes = new HashMap(); attributes.put("make", "Ford"); attributes.put("model", "ModelT"); NewRelic.recordCustomEvent("Car", "Ford Model T", attributes); ``` #### Kotlin [#kotlin] ```kotlin val attributes = mutableMapOf() attributes["make"] = "Ford" attributes["model"] = "ModelT" NewRelic.recordCustomEvent("Car", "Ford Model T", attributes); ``` ## iOS > #### ⚠️ IMPORTANT > > As of New Relic [iOS agent version 5.12.0](https://docs.newrelic.com/docs/release-notes/mobile-release-notes/ios-release-notes/ios-agent-5120), the `recordEvent` method is deprecated and replaced with `recordCustomEvent`. The `recordEvent` method will continue to work for an unspecified period of time, but if your app contains `recordEvent` methods, New Relic recommends you replace them. > > Updating these methods will affect any queries and dashboards that use the deprecated event types. Be sure to adjust your NRQL queries and dashboards as needed. ### Syntax [#syntax] #### Objective-c [#objc] ```objectivec + (BOOL) recordCustomEvent:(NSString*)eventType attributes:(NSDictionary*)attributes; ``` ```objectivec + (BOOL) recordCustomEvent:(NSString*)eventType name:(NSString*)name attributes:(NSDictionary*)attributes; ``` #### Swift [#swift] ```swift NewRelic.recordCustomEvent(eventType: String!, attributes:[NSObject : AnyObject]!) -> Bool ``` ```swift NewRelic.recordCustomEvent(eventType: String!, name: String!, attributes:[NSObject : AnyObject]!) -> Bool ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/insights-data-sources/custom-events/insert-query-custom-mobile-app-events-attributes) that you can query using [NRQL](https://docs.newrelic.com/docs/query-data/nrql-new-relic-query-language/getting-started/introduction-nrql). The event includes a list of attributes, specified as a map. Unlike using [`setAttribute`](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/), adding attributes to a custom event adds them only to that event; they are not session attributes. Important considerations and best practices include: - Limit the total number of `eventType` values to approximately five. It is meant to be used for high-level categories, such as `Gestures.` - Do not use `eventType` to name your custom events. Instead, create attributes to name custom events, or use the optional `name` parameter. - Use the `name` keyword to display your events in the [mobile monitoring UI](https://docs.newrelic.com/docs/mobile-monitoring/mobile-monitoring-ui/mobile-app-pages/mobile-apps-index). To create a useful name, you can combine several attributes. Using the `name` parameter has the same effect as adding a `name` key in the attributes dictionary. - The elements of the attributes object must be of the type NSString or NSNumber. ### Parameters [#parameters] | Parameter | Type | Description | | ------------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `$eventName` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `$eventAttributes` | `dictionary` | Optional. A map that includes a list of attributes that further designate subcategories to the `$eventType`. The elements of the attributes object must be of the type NSString or NSNumber. You can create attributes for any event descriptors you think will be useful. To name your custom events, create a `name` attribute or use the `eventName` parameter. > #### ⚠️ IMPORTANT > > When setting the key for your custom attributes, be aware that there are [default attributes that cannot be overridden](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/). | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Examples [#examples] #### Objective-C [#obj-c] ```objectivec BOOL eventRecorded = [NewRelic recordCustomEvent:@"eventType" attributes:@{@"attributeName1": @"value1", @"attributeName2": @2}]; ``` ```objectivec BOOL eventRecorded = [NewRelic recordCustomEvent:@"Vehicle" name:@"1908 Ford ModelT" attributes:@{@"make":@"Ford", @"model":@"ModelT", @"year": @1908, @"color": @"black", @"mileage": @250000}]; ``` #### Swift [#swift] ```swift let eventRecorded = NewRelic.recordCustomEvent("eventType", attributes: ["attributeName1" : "value1", "attributeName2": 2]) ``` ```swift let eventRecorded = NewRelic.recordCustomEvent("Vehicle", name:"1908 Ford ModelT", attributes:["make":"Ford", "model":"ModelT", "year": 1908, "color": "black", "mileage": 250000]); ``` ## Capacitor ### Syntax [#syntax] ```typescript recordCustomEvent(options: { eventType: string; eventName: string; attributes: object; }) => void ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `eventName` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `attributes` | `object` | Optional. A map that includes a list of attributes that further designate subcategories to the `eventType`. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```typescript NewRelicCapacitorPlugin.recordCustomEvent({ eventType: "mobileClothes", eventName: "pants", attributes:{"pantsColor": "blue","pantssize": 32,"belt": true} }); ``` ## Cordova ### Syntax [#syntax] ```typescript recordCustomEvent(eventType: string, eventName?: string, attributes?: {[key: string]: boolean | number | string}): void; ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `eventName?` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `attributes?` | `dictionary` | Optional. A map that includes a list of attributes that further designate subcategories to the `eventType`. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```js NewRelic.recordCustomEvent("mobileClothes", "pants", {"pantsColor": "blue", "pantssize": 32, "belt": true}); ``` ## .NET MAUI ### Syntax [#syntax] ```csharp RecordCustomEvent(string eventType, string eventName, Dictionary attributes): bool; ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. In addition to any custom attributes you choose, the event will also have associated [session attributes](https://docs.newrelic.com/docs/insights/explore-data/attributes/mobile-default-attributes-insights#mobile-list). Unlike with using [`setAttribute`](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/), adding attributes to a breadcrumb event adds them only to that event; they are not session attributes. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `eventName` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `attributes` | `Dictionary` | Optional. A dictionary of key-value pairs that can be used to provide additional information about the custom event. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```C# CrossNewRelic.Current.RecordCustomEvent("MAUICustomEvent", "MAUICustomEventCategory", new Dictionary() { {"BreadNumValue", 12.3 }, {"BreadStrValue", "MAUIBread" }, {"BreadBoolValue", true } } ); ``` ## Flutter ### Syntax [#syntax] ```dart recordCustomEvent(String eventType,{String eventName = "", Map? eventAttributes}): void; ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ----------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `eventName` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `eventAttributes` | `dictionary` | Optional. A map that includes a list of attributes that further designate subcategories to the `eventType`. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```dart NewrelicMobile.instance.recordCustomEvent("Major",eventName: "User Purchase",eventAttributes: {"item1":"Clothes","price":34.00}); ``` ## React Native ### Syntax [#syntax] ```js recordCustomEvent(eventType: string, eventName?: string, attributes?: {[key: string]: any}): void; ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events; use a custom attribute or the optional `name` parameter. | | `eventName` | `string` | Optional. Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `attributes` | `dictionary` | Optional. A map that includes a list of attributes that further designate subcategories to the `eventType`. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```js NewRelic.recordCustomEvent("mobileClothes", "pants", {"pantsColor": "blue","pantssize": 32,"belt": true}); ``` ## Unity ### Syntax [#syntax] ```csharp RecordCustomEvent(string name, Dictionary attributes): bool; ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `name` | `string` | Use this parameter to name the event. Using this parameter is equivalent to creating a `name` parameter. | | `attributes` | `Dictionary` | Optional. A dictionary of key-value pairs that can be used to provide additional information about the custom event. | ### Return values [#return-values] Returns `true` if the event is recorded successfully, or `false` if not. ### Example [#example] ```csharp Dictionary dic = new Dictionary(); dic.Add("Unity Custom Attribute", "Data2"); NewRelicAgent.RecordCustomEvent("Unity Custom Event Example", dic); ``` ## Unreal Engine ### Syntax [#syntax] ```cpp recordCustomEvent(FString eventType, TMap eventAttributes):void recordCustomEventWithEventType(FString eventType,FString eventName, TMap eventAttributes):void ``` ### Description [#description] Creates and records a [custom event](https://docs.newrelic.com/docs/insights/new-relic-insights/adding-querying-data/custom-attributes-events-new-relic-mobile#What-are-events-in-New-Relic-Mobile), for use in NRQL. ### Parameters [#parameters] | Parameter | Type | Description | | ------------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `$eventType` | `string` | Required. The type of event. Do not use `$eventType` to name your custom events. Instead, use a custom attribute or the optional `name`. | | `$eventName` | `eventAttributes` | Optional. A map that includes a list of attributes that further designate subcategories to the `$eventType`. You can create attributes for any event descriptors you think will be useful. To name your custom events, create a `name` attribute or use the `eventName` parameter. Note: Not all object types are supported. See [setAttribute](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute//#parameters) for details on supported types. > #### ⚠️ IMPORTANT > > When setting the key for your custom attributes, be aware that there are [default attributes that cannot be overridden](https://docs.newrelic.com/docs/mobile-monitoring/new-relic-mobile/mobile-sdk/create-attribute/#description). | ### Example [#example] ```cpp #include "NewRelicBPLibrary.h" TMap customEventMap; customEventMap.Add("place", TEXT("Robots")); customEventMap.Add("user", TEXT("user1")); UNewRelicBPLibrary::recordCustomEvent("Unreal Custom Event Example", customEventMap); TMap customEventMap; customEventMap.Add("place", TEXT("Robots")); customEventMap.Add("user", TEXT("user1")); UNewRelicBPLibrary::recordCustomEvent("Unreal Custom Event Type","Unreal Custom Event Example", customEventMap); ``` ![Screenshot of the Unreal Engine Plugin Record Custom Event](https://docs.newrelic.com/images/newrelic_unreal_sdk_record_custom_event.webp "Unreal Engine Plugin Record Custom Event")