Mobile React Native agent API

BETA

In addition to automatic instrumentation, New Relic Mobile's React Native agent offers a custom instrumentation API. You can make your own calls with React Native methods, as well as with a variety of iOS and Android methods.

Requirements

Before using the Mobile React Native agent API, ensure you meet the React Native agent requirements.

React Native API methods

The agent supports the following React Native methods:

recordBreadcrumb

Creates and records a MobileBreadcrumb event.

NewRelic.recordBreadcrumb(string $Name, map<string, number> $eventAttributes) 
Parameter Description

eventName

string

Required. The name you want to give to the breadcrumb event.

attributes

map <string, number>

Optional. A map that includes a list of attributes of the breadcrumb event. Create attributes for any event descriptors you think will be useful.
recordCustomEvent

Creates and records a custom event, for use in New Relic Insights. The event includes a list of attributes, specified as a map.

NewRelic.recordCustomEvent(string $eventType, [string $eventName,] map<string, number> $eventAttributes) 
Parameter Description

$eventType

string

Required. The type of event, and the highest level way of grouping data.

$eventName

string

Optional. Use this parameter to further categorize your custom event data. (Using this parameter is equivalent to creating a name parameter.)

$attributes

map <string, number>

Optional. A map that includes a list of attributes.
setAttribute

Creates a custom attribute with a specified name and value. When called, it overwrites its previous value and type. The created attribute is shared by multiple Mobile event types.

NewRelic.setAttribute(string $attributeName, string $value)
Parameter Description

$attributeName

string

Required. The type name of the attribute.

$value

string, <number, boolean>

Required. The second parameter passed can be either a number value or a boolean value.

setJSAppVersion

Sets the JavaScript release version.

NewRelic.setJSAppVersion(string $version)
Parameter Description

$version

string

Use this API to differentiate your JavaScript app version from the version of the app deployed into the app store. This API is useful when using JS code push.
setUserId

Set a custom user identifier value to associate user sessions with analytics events and attributes.

NewRelic.setUserId(string $userId)
Parameter Description

$userId

string

Required. Sets a custom user identifier value to associate mobile user.

Session management

The React Native agent supports the following method for mobile sessions. You can query session data with MobileSession events. The MobileSession events are generated at the beginning of a session instead of the end.

continueSession
NewRelic.continueSession()
Parameter Description

None

New Relic API calls automatically continue sessions, but for non-instrumented app activity, you can use continueSession to extend the current session until the timeout period has elapsed. The default session timeout is 30 minutes.

New Relic's Android and iOS agents set mobile sessions to end automatically when a mobile app is put in the background. With New Relic's Mobile React Native agent, your end users can background the mobile app multiple times, but the session will only end after 30 minutes of user inactivity. This provides better context for what happens during their use. You can also keep a session open for longer periods, based on functionality of your app.

Use the continueSession API call to keep sessions open longer when you want an action taken by the app, not the user, to indicate an active session. This is useful, for example, for:

  • tvOS, where viewers keep a TV or a movie on for hours but don't interact with the app
  • Exercise programs, where users keep the app running for an hour to track their exercise, but they don't interact with the app until after they finish
  • A user wants to respond to a text before returning to the mobile app to finish browsing, purchasing, etc.

Continuing sessions will affect the crash rate (count of crashes / count of sessions). When a session captures a customer's interactions over a longer time period, the crash rate may be much larger. Fewer sessions, with the same number of crashes in the application will raise the crash rate. How much the crash rate changes is entirely dependent on the functionality of the app, and user flows therein. In contrast, our Android and iOS agents will report much lower crash rates, as new sessions are more frequent in a user's workflow.

Crash rate example:

If a customer goes in and out of your app 5 times in 10 minutes while switching to texting and other apps, the Android or iOS agents reflect the crash that ended their use in the last session. Using continueSession with the React Native agent, all of those 5 times will be counted as one session, so 100% ( 1 crash / 1 session ) of that session will have a crash, rather than 20% ( 1 crash / 5 sessions ).

API example:

To include the continueSession API call when receiving a push notification:

function receivePushNotification(notification: PushNotification): ThunkAction {
  return dispatch => {
    const { foreground, message } = notification;
    const data = normalizeData(notification.data);

    if (!foreground) {
      dispatch(switchTab("info"));
    }
    
    const timestamp = new Date().getTime();
    dispatch({
      type: "RECEIVED_PUSH_NOTIFICATION",
      notification: {
        text: message,
        url: data.url,
        urlTitle: data.urlTitle,
        image: data.image,
        video: data.video,
        time: timestamp
      }
    });
    NewRelic.continueSession();
  };
}

iOS SDK API methods

Many native iOS SDK API methods are supported with the React Native agent, including:

Android SDK API methods

Many Android SDK API methods are supported with the React Native agent, including:

In addition, the following native Android SDK API method is only supported with the React Native agent:

setJSAppVersion
Parameter Description

$version

string

Use this API to differentiate your JavaScript app version from the version of the app deployed into the app store. Define a non-null, non-empty unique string representing the app version. This API is useful when using JS code push.

For more help

During the public beta, we welcome your questions and comments through the React Native beta discussion board in New Relic's Explorers Hub. Support requests also will be routed here.