Customize the React Native Instrumentation

The sections below describe how to use the React Native APIs to customize your instrumentation.

Using the React Native Agent APIs

After you have installed and initialized the React Native Agent, you instrument your application code by importing the class, interface, or enumeration and then calling API methods.

Import Syntax

To access the React Native Agent APIs, use an import statement at the top of the file. The following line imports the class Instrumentation:

import { Instrumentation } from '@appdynamics/react-native-agent';

API Method Syntax

Once the class, interface, or enumeration has been imported, call the API methods from the imported component. In this example, you set custom user data with setUserDataBoolean from the Instrumentation class.

Instrumentation.setUserDataBoolean("Boolean Key", true);

Change the App Key

You can use the React Native API to dynamically change the EUM App Key. You receive the app key when creating a mobile app in the Controller UI. See Set Up and Access Mobile RUM for more information about app keys. 

Class

The API to change app keys is available through the Instrumentation class.

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

The API consists of the following method:

• changeAppKey(appKey)

Method Parameters

The changeAppKey method takes the following parameter:

Examples

In this example, you create a method that takes a new app key and passes it to the API method changeAppKey.

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private updateAppKey(newAppKey) {
    Instrumentation.changeAppKey(newAppKey);
}

Collect Additional Types of Data

The React Native APIs have methods that extend the application data types you can collect and aggregate with Mobile RUM. There are six basic kinds of extensions that you can create:

import { InfoPoint } from '@appdynamics/react-native-agent';

import { InfoPoint } from '@appdynamics/react-native-agent';

class InfoPointsScreen extends Component {

  @InfoPoint 
  public infoPointMethod(arg1, arg2, value) {
    console.log("Executing infoPointMethod!"); 
  }
} 

import { InfoPoint } from '@appdynamics/react-native-agent';

class InfoPointsScreen extends Component {

  @InfoPoint({ className: 'MyClass', fnName: 'infoPointMethod' })
  public infoPointMethod(arg1, arg2, value) {
    console.log("Executing infoPointMethod!"); 
  }
}

Class/Interface

The Custom Timers API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

You create the custom timers using the following React Native Agent API methods:

• startTimerWithName(name)

• stopTimerWithName(name)

Method Parameters

Both methods take the following parameter:

Examples

For example, to track the time a user spends viewing a screen, the instrumentation could look like this:

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private startCustomTimer() {
  Instrumentation.startTimer("My timer");
}
private stopCustomTimer() {
   Instrumentation.stopTimer("My timer");
}

Create Custom Metrics

The React Native API enables you to report custom metrics. You specify the name of the custom metric that will appear in the Controller UI.

Class

The Custom Metrics API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

You create custom metrics with the reportMetric:

• reportMetric(name, value) 

Method Parameters

The reportMetric method takes the following parameters:

Examples

For example, the following method could be used to report custom metrics:

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private reportMetrics() {
    Instrumentation.reportMetric("Normal metric", 23);
    Instrumentation.reportMetric("Large metric", Number.MAX_SAFE_INTEGER + 1);
    Instrumentation.reportMetric("Small metric", Number.MIN_SAFE_INTEGER - 1);
}

Add Custom User Data

Use the Custom User Data API to set and remove key/value pairs of different data types. The key must be unique across your application.

Class

The Custom User Data API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

The API provides the following methods for setting and removing custom user data:

Method Parameters

The following table lists the parameters for the methods for setting custom user data.

The following table lists the parameters for the methods for removing custom user data.

The method removeUserData is called when setting custom data to the value null. For example, the method Instrumentation.setUserData("name", null) will call Instrumentation.removeUserData("name").

Examples

The following code example shows how to set and remove user data with the Custom User Data API:

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private setUserData() {
    Instrumentation.setUserData("userId", "AISJ1723871");
    Instrumentation.setUserDataBoolean("isVip", true);
    Instrumentation.setUserDataDate("purchaseDate", new Date(1234567890));
    Instrumentation.setUserDataDouble("monthlyVisits", 1.2345);
    Instrumentation.setUserDataInteger("totalPurchasedItems", 42);
}
private clearUserData() {
    Instrumentation.removeUserData("userId", null);
    Instrumentation.removeUserDataBoolean("isVip", null);
    Instrumentation.removeUserDataDate("purchaseDate", null);
    Instrumentation.removeUserDataDouble("monthlyVisits", null);
    Instrumentation.removeUserDataInteger("totalPurchasedItems", null);
}

Leave Breadcrumbs

Breadcrumbs enable you to situate a crash in the context of your user's experience. Set a breadcrumb when something interesting happens. If your application crashes at some point in the future, the breadcrumb will be displayed along with the crash report. Each crash report displays the most recent 99 breadcrumbs.

Class

The Breadcrumb API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

You create and leave breadcrumbs with the following API method:

• leaveBreadcrumb(breadcrumb, mode)

Method Parameters

The method leaveBreadcrumb takes the following parameters:

Examples

Basic Usage

The following example shows the syntax and usage of the Breadcrumb API. 

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private leaveBreadcrumb() {
    Instrumentation.leaveBreadcrumb("Drop a breadcrumb button implementation", BreadcrumbVisibility.CRASHES_AND_SESSIONS);
}

Extended Use Case

Supposed your React Native app has a wizard that shows different steps of a process sequentially on the same screen. In the case of a crash or an "Application Not Responding" (ANR) error, you would want to know what step of the wizard caused the crash or ANR.

If your app had a wizard engine similar to the one below, you could leave a breadcrumb for each screen to track events and issues.

async function wizard(...screens) {
    let currentScreen = 0;
    while (true) {
        const screen = screens[currentScreen];
        if (screen == null) return;
        // Report the current screen with AppDynamics instrumentation
        Instrumentation.leaveBreadcrumb('wizard screen ' + screen.name);
        currentScreen += await screen.action();
    }
}

The wizard engine could be used for a checkout:

wizard(
    { name: 'review cart', action:reviewCartAction },
    { name: 'chose payment', action:chosePaymentAction },
    { name: 'chose address', action:choseAddressAction },
    { name: 'review order', action:reviewOrderAction },
    { name: 'checkout', action:checkoutAction }
)

Capture User Interaction

The React Native Agent can track certain UI events triggered by user interactions. Once user interactions have been captured, you can sort sessions by UI event and view UI events in the timeline of the session waterfall. 

Supported User Interactions

You can capture when users do one or all of the following:

• press buttons
• select table cells
• select text fields
• select text views

Security and Privacy Concerns

The interaction capture mode is disabled by default for security and privacy reasons, as user interactions may contain sensitive information. Moreover, this potential security and privacy issue may be compounded if you enable both the capturing of UI interactions and screenshots. 

Class

The Interaction Capture Mode API is accessible through the InteractionCaptureMode class, but you also need the Instrumentation class to start instrumentation with the configured user capture mode.

import { Instrumentation, InteractionCaptureMode } from '@appdynamics/react-native-agent';

Properties

The following properties are accessed through the InteractionCaptureMode class and used to configure the user interaction capture. For example: InteractionCaptureMode.All

Methods

The API methods take an array of user interaction capture modes and return an InteractionCaptureMode object that determines which user interactions will be captured. The methods do not mutate the object.

Examples

Set User Interaction Mode with API Properties

The following example configures the React Native Agent to capture all user interactions.

import { Instrumentation, InteractionCaptureMode } from '@appdynamics/react-native-agent';
...
Instrumentation.start({
     appKey: <EUM_APP_KEY>,
     // ...your other configurations

     // Capture all user interactions
     interactionCaptureMode: InteractionCaptureMode.All
 })

Combine User Interaction Modes

In the following example, the with method combines the ButtonPressed (button presses) and TextFieldSelected (text field selected) modes with the None mode, effectively just enabling those two user interaction modes. 

import { Instrumentation, InteractionCaptureMode } from '@appdynamics/react-native-agent';
...
Instrumentation.start({
    appKey: <EUM_APP_KEY>,
    // ...your other configurations

    // Only enable "ButtonPressed" and "TextFieldSelected" interaction modes, and disable the rest.
    interactionCaptureMode: InteractionCaptureMode.None.with(
        InteractionCaptureMode.ButtonPressed,
        InteractionCaptureMode.TextFieldSelected
    )
})

import { Instrumentation, InteractionCaptureMode } from '@appdynamics/react-native-agent';
...
Instrumentation.start({
    appKey: <EUM_APP_KEY>,
    // ...your other configurations

    // Include all capture modes except "ButtonPressed" and "TextFieldSelected".
    interactionCaptureMode: InteractionCaptureMode.All.without(
        InteractionCaptureMode.ButtonPressed,
        InteractionCaptureMode.TextFieldSelected
    )
})

import { Instrumentation } from '@appdynamics/react-native-agent';
...
Instrumentation.shutdownAgent();

import { Instrumentation } from '@appdynamics/react-native-agent';
...
Instrumentation.restartAgent();

Programmatically Control Sessions

By default, a mobile session ends after a period of user inactivity. For example, when a user opens your application, the session begins and only ends after the user stops using the app for a set period of time. When the user begins to use the application again, a new session begins. Instead of having a period of inactivity to define the duration of a session, however, you can use this API to programmatically control when sessions begin and end.

Class

The API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

JS

Methods

The API provides the following method for ending the current session and starting a new session:

Method	Description
startNextSession()	When you call the method startNextSession from Instrumentation, the current session ends and a new session begins. The API enables you to define and frame your sessions so that they align more closely with business goals and expected user flows. For example, you could use the API to define a session that tracks a purchase of a product or registers a new user.

Excessive use of this API will cause sessions to be throttled (excessive use is >10 calls per minute, but is subject to change). When not using the API, sessions will fall back to the default of ending after a period of user inactivity. 

Examples

In the following example, the current session ends and a new one begins when the check out is made.

import { Instrumentation } from '@appdynamics/react-native-agent';
...
private checkoutCart(){
    if (currentCartItems!=null && currentCartItems.size()>0){
	    CheckoutTask checkoutReq = new CheckoutTask();
		checkoutReq.execute(getEndpoint() + "cart/co");
		currentCartItemsMap.clear();
		convertItemsMaptoList();
        Instrumentation.startNextSession();
	} else {
	    displayToast("There are no items in the cart");
	}
}

Start and End Session Frames

You can use the React Native Agent API to create session frames that appear in the session activity. Session frames provide context for what the user is doing during a session. With the API, you can improve the names of user screens and chronicle user flows within a business context. 

Use Cases

The following are common use cases for session frames: 

• One page performs multiple functions and you want more granular tracking of the individual functions.
• A user flow spans multiple pages or user interactions. For example, you could use the API to create the session frames "Login", "Product Selection", and "Purchase" to chronicle the user flow for purchases.
• You want to capture dynamic information based on user interactions to name session frames, such as an order ID.

Class/Interface

The SessionFrame API is accessible through the Instrumentation class.

import { Instrumentation } from '@appdynamics/react-native-agent';

To update the name and end a session frame, you would use the SessionFrame interface.

Methods

The following table lists the three methods you can use with session frames. In short, you start a session frame with startSessionFrame and then use updateName and end to rename and end the session frame. 

Method Parameters

The methods startSessionFrame and updateName takes the following parameter:

Session Frame Example

In the following example, session frames are used to track user activity during the checkout process.

let sessionFrame: SessionFrame | undefined;

private onCheckoutCartButtonClicked() {
    // The user starts the checkout by clicking the checkout button.
    // This may be after they have updated the quantities of items in the cart, etc.
    sessionFrame = Instrumentation.startSessionFrame("Checkout");
}
private onConfirmOrderButtonClicked() {
    // Once they have confirmed payment info and shipping information, and they
    // are clicking the "Confirm" button to start the backend process of checking out,
    // we may know more information about the order itself, such as an order ID.
    if (sessionFrame) {
        sessionFrame.updateName("Checkout: Order ID " + orderId);
    }
}
private onProcessOrderCompleted() {
    // Once the order is processed, the user is done "checking out", so we end the session frame.
    if (sessionFrame) {
            sessionFrame.end();
            sessionFrame = null;
    }
}
private onCheckoutCancled() {
  // If the user cancels or returns to the cart, you'll want to end the session frame also, or else it will be
    // left open and appear to have never ended.
    sessionFrame.end();
    sessionFrame = null;
  }
}

Configure and Take Screenshots

By default, mobile screenshots are enabled on the agent-side but disabled on the Controller-side. These screenshots appear in the Controller in the Sessions Details dialog. To programmatically take manual screenshots, you must enable screenshots in the Controller UI and add the Screenshot API below. 

Class

The Screenshot API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

Methods

The Screenshot API provides the following methods:

Configure Screenshots

Disable Screenshots

You can disable screenshots from the Controller UI or with the React Native API. To disable screenshots, set the property screenshotsEnabled to false when initializing the Native React Agent.

Instrumentation.start({
    appKey: <EUM_APP_KEY>,
    screenshotsEnabled: false,
    ...
});

Set On-Prem Screenshot Service

If you have deployed an on-prem EUM Server, you will need to specify the URL to the EUM Server with the property screenshotURL.

Instrumentation.start({
    appKey: <EUM_APP_KEY>,
    screenshotURL: "https://<COLLECTOR_URL>:<PORT>",
    ...
});

Examples

Take Screenshots

You can configure the Controller UI to automatically take screenshots or use the React Native API to manually take a screenshot as shown below:

private loadShoppingCart() {
  // Load shopping cart
  this.setState({
      shoppingCart: this.state.cart
  });
  // Manually take screenshot
  Instrumentation.takeScreenshot();
}

This will capture everything, including personal information, so precaution is necessary when taking screenshots

Block and Unblock Screenshots

You can also block screenshots from being taken during the execution of a code block. This just temporarily blocks screenshots from being taken until you unblock screenshots. This enables you to stop taking screenshots in situations where users are entering personal data, such as on login and account screens. 

private displayCustomerAccount() {
    // Check to see if screenshots are blocked
    if (! Instrumentation.screenshotsBlocked()) {
        // If screenshots aren't blocked, block them before showing customer details 
        Instrumentation.blockScreenshots();     
    }  
    // Code to display customer details
    
    // After you're done, unblock screenshots
    Instrumentation.unblockScreenshots();
}

Enable Logging and Set Logging Level

You enable logging by setting the logging level in the instrumentation configuration. You are recommended to disable logging for production. 

Class 

The Logging Level API is accessible through the LoggingLevel class:

import { LoggingLevel } from '@appdynamics/react-native-agent';

Configuration Properties

You enable and set the logging level with the following configuration property:

LoggingLevel.NONE

LoggingLevel.INFO

LoggingLevel.VERBOSE

Examples

In the following example, logging is enabled and the logging level is set to VERBOSE:

private async start() {
        try {
            await Instrumentation.start({
                appKey: this.state.appKey,
                loggingLevel: LoggingLevel.VERBOSE, 
                anrDetectionEnabled: true,
                interactionCaptureMode: InteractionCaptureMode.None.with(
                    InteractionCaptureMode.ButtonPressed,
                    InteractionCaptureMode.ListViewItemSelected,
                    InteractionCaptureMode.TableCellSelected,
                    InteractionCaptureMode.TextFieldSelected,
                    InteractionCaptureMode.TextViewSelected
                )
            }
        )
    }
}

Receive a Crash Report Summary for Native Crashes

You can use CrashReportCallback to receive a report for native crashes. 

Class 

The CrashReportCallback API is accessible through the Instrumentation class:

import { Instrumentation } from '@appdynamics/react-native-agent';

How to Use

1. Submit the CrashReportCallback object as the crashReportCallback native agent configuration option. 

   Instrumentation.start({
         crashReportCallback: (summaries: CrashReportSummary[]) => {
             console.log(summaries);
         },
    });

   CODE

2. On application restart, you will receive a CrashReportSummary for each crash.

   export type CrashReportSummary = {
     crashId: string;  
     exceptionName: string; 
     exceptionReason: string;
     signalName: string;
     signalCode: string;
   };

   CODE

CrashReportSummary Properties

CrashReportSummary has the following properties:

Disable Crash Reporting

Crash reporting is enabled by default, but you can manually disable crash reporting through the instrumentation configuration. If you are using other crash reporting tools, you might disable crash reporting to minimize conflicts and optimize the crash report results. 

You can disable crash reporting by configuring the instrumentation with the crashReportingEnabled property as shown in the following:

import { Instrumentation } from '@appdynamics/react-native-agent';

Instrumentation.start({
        appKey: <#EUM_APP_KEY#>,
        crashReportingEnabled: false
})

Report Errors and Exceptions

You can report exceptions using the method reportError from the Instrumentation class. Reported exceptions will appear in session details.

You can also set one of the severity levels below for an issue. With the severity level, you can filter errors in the Code Issues Dashboard or Code Issues Analyze.

• ErrorSeverityLevel.INFO
• ErrorSeverityLevel.WARNING

• ErrorSeverityLevel.CRITICAL

The example below uses the API to report possible exceptions and sets the severity level to ErrorSeverityLevel.CRITICAL (critical) when writing to a file

import { Instrumentation, ErrorSeverityLevel} from '@appdynamics/react-native-agent';
...
try {
  await asyncTask();
catch (error) {
  Instrumentation.reportError(error, ErrorSeverityLevel.CRITICAL);
}
...

Log Silenced Errors

If you use React Native's ErrorBoundary, the errors are silently caught, but the agent will not receive and log them. If you want silenced crashes to be logged, we recommend you use ErrorBoundary provided in the AppDynamics React Native package:

import { ErrorBoundary } from '@appdynamics/react-native-agent'

Use the Agent with a Custom HTTP Library

The agent automatically detects network requests when the underlying implementation is handled by NSURLConnection/NSURLSession classes (iOS) or HttpURLConnection/OkHttp (Android). This covers most network requests, but in some cases, mobile applications use custom HTTP libraries. 

To enable the agent to detect requests from a custom library, add request tracking code to your application manually with the RequestTracker class. 

 You must initialize the agent with a valid key using the Instrumentation.start() interface before using this method.

RequestTracker Properties

The following properties should be set on the RequestTracker object to describe the parameters of the custom call.

tracker.setError(e);

tracker.setResponseStatusCode(response.statusCode); 

tracker.setRequestHeaders(headers); 

tracker.setResponseHeaders(headers);

Track a Custom HTTP Request

To add manual request tracking, you must specify when the request begins, when it ends and what the status of the response is. 

1. Create a RequestTracker object immediately before sending the request:

import { Instrumentation } from '@appdynamics/react-native-agent';
...
const tracker = new RequestTracker({ "My_URL" }); 

"MY_URL" is the URL being called. This parameter must not be null.

2. (Optional) Add your custom headers to the tracker before sending the request:

 const headers = {
  'Content-Length': '5000',
 	};
 tracker.setRequestHeaders(headers);

requestHeaders: A dictionary (or null) representing the keys and values from the request headers.

3. (Optional) Enable correlation between your request and server-side processing. Add specific headers to outgoing requests that the server-side agent can detect and return the headers obtained from the server-side agent in the response to make them available to the agent:

tracker.addServerCorrelationHeaders()

4. Immediately after receiving a response or an error, set properties on the tracker object based on whether the request finished successfully or ended in error:

try {
    const response = await customRequest(url);
    tracker.setResponseStatusCode(response.statusCode);
    tracker.setResponseHeaders(response.headers);
} catch (e) {
    tracker.setError(e);
}

6. Call reportDone():

tracker.reportDone();

To track another request, instantiate a new tracker object again.

Complete example

const tracker = new requestTracker({
  url: <MY_URL>
});


const headers = {
  'Content-Length': '5000',
};
tracker.setRequestHeaders(headers);
tracker.addServerCorrelationHeaders();


try {
  const response = await customRequest(url);
  tracker.setResponseStatusCode(response.statusCode);
  tracker.setResponseHeaders(response.headers);
} catch (e) {
  tracker.setError(e);
} finally {
  tracker.reportDone();
}

React Native API Documentation

For the React Native Agent API reference documentation, see the latest React Native Agent API documentation or the previous versions:

• https://sdkdocs.appdynamics.com/react-native-agent/21.4/
• https://sdkdocs.appdynamics.com/react-native-agent/21.2/
• https://sdkdocs.appdynamics.com/react-native-agent/20.11/
• https://sdkdocs.appdynamics.com/react-native-agent/20.10/
• https://sdkdocs.appdynamics.com/react-native-agent/20.7/
• https://sdkdocs.appdynamics.com/react-native-agent/1/1.0/