React Native Monitoring API

Instana React Native agent API

The following section describes the usage of the Instana React Native agent. Instana's React Native agent can be used via the Instana class methods explained below.

Setup

We recommend initializing Instana in your App class' componentDidMount(), as early as possible:

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL);
  }
}

Parameters

Parameter
Description
key (String) Instana monitoring configuration key
reportingURL (String) URL pointing to the Instana instance to which to the send monitoring data to

Session Identifier

Each Instana agent instance has an unique session identifier you could use for other purposes in your app.

static getSessionID()

Parameters

Returns: Promise(String)

Example

var sessionID = await Instana.getSessionID();

Automatic HTTP monitoring

HTTP sessions will be be captured automatically. Please refer to the documentation specific to each platform for more details.

Views

Instana can segment mobile app insights by logical views. To do so, set the view name via the Instana.setView(String) method. The view will then be associated to all monitored beacons until the view changes once setView is called again.

We recommend not to use technical or generic names like the Class (e.g. WebViewActivity) to define views. We recommend the usage of readable names for views, for example product detail page or payment selection. Focusing on what users are experience will allow team members without intimate knowledge of the codebase to understand the insights provided.

Note: Instana.setView(String) should be called when a screen is presented to the user, rather than when a screen is created (as in a Fragment which could be created once but shown multiple times). Setting the view name will also enable Instana to track page transitions in addition to page loads.

static setView(String name)

Parameters

Parameter
Description
name (String) The name of the view.

Example

Instana.setView('Webview: FitBit authorization');

Identifying Users

User-specific information can optionally be sent with data transmitted to Instana. This information can then be used to unlock additional capabilities such as:

  • calculate the number of users affected by errors,
  • to filter data for specific users and
  • to see which user initiated a view change or HTTP request.

By default, Instana will not associate any user-identifiable information to beacons. Please be aware of the respective data protection laws when choosing to do so. We generally recommend identification of users via a user ID. For Instana this is a completely transparent String that is only used to calculate certain metrics. userName and userEmail can also be used to have access to more filters and a more pleasant presentation of user information.

In cases in which you are handling anonymous users and thus don't have access to user IDs you could alternatively use session IDs. Session IDs are not as helpful as user IDs when filtering data but they are a good indicator to calculate affected/unique user metrics. We recommend setting a user name such as Anonymous to have a clear differentiation between authenticated and unauthenticated users. Session IDs can be sensitive data (depending on the framework/platform used). Please consider hashing session IDs to avoid transmitting data to Instana that can grant access.

It is important to note that data already transmitted to Instana's server cannot be retroactively updated. For this reason it is important to call this API as early as possible in the app launch process.

static setUserID(String id)
static setUserName(String email)
static setUserEmail(String name)

Parameters

Parameter
Description
id (String) An identifier for the user.
email (String) The user's email address.
name (String) The user's name.

Example

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL);
    Instana.setUserID('1234567890');
    Instana.setUserEmail('[email protected]');
    Instana.setUserName('instana react-native agent demo');
  }
}

Meta data

Arbitrary meta data can optionally be attached to all data transmitted to Instana. Consider using this to track UI configuration values, settings, feature flags… any additional context that might be useful for analysis.

Note: we currently support up to 50 meta key/value pairs.

static setMeta(String key, String value)

Parameters

Parameter
Description
value (String) The value of the key-value pair you want to add as meta data.
key (String) The key of the key-value pair you want to add as meta data.

Example

export default class App extends Component {
  componentDidMount() {
    Instana.setMeta('randomKey1', 'randomValue1');
    Instana.setMeta('randomKey2', 'randomValue2');
  }
}

Report Custom Events

Custom events enable reporting about non-standard activities, important interactions and custom timings to Instana. This can be especially helpful when analyzing uncaught errors (breadcrumbs) and to track additional performance metrics.

static reportEvent(String eventName, {
  startTime: Number startTime,
  duration: Number duration,
  viewName: String viewName,
  backendTraceId: String backendTraceId,
  meta: Map meta
})

Parameters

Parameter
Description
eventName (String) Defines what kind of event has happened in your app that should result in the transmission of a custom beacon.
startTime (Number, optional) A timestamp in milliseconds since Epoch indicating at which time the event started. Falls back to now() - duration when not defined.
duration (Number, optional) The duration in milliseconds of how long the event lasted. Default is zero
viewName (String, optional) You can pass a String to group the request to a view. If you send explicitly nil, the viewName will be ignored. Alternatively you can leave out the parameter viewName to use the current view name you did set in setView(String name))
backendTracingId (String, optional) Identifier to create a backend trace for this event.
meta (object, optional) A JavaScript object with string values which can be used to send metadata to Instana just for this singular event. In contrast to the usage of the metadata API, this metadata is not included in subsequent beacons.

Example

Instana.reportEvent('myCustomEvent', {
  startTime: Date.now() - 500,
  duration: 300,
  viewName: 'overridenViewName',
  backendTracingId: '31ab91fc1092',
  meta: {
    state: 'running'
  }
});

Excluding URLs from Monitoring

URLs can be ignored by providing regular expressions, by adding them to the ignoreURLs list. A good scenario for usage of this function would be to ignore all HTTP requests that contain any sensitive data like a password.

Please keep in mind that the Agent needs to convert each String you provide to the setIgnoreURLsByRegex method into a native regex expression for each supported platform. We highly encourage you to track any Promise rejections, which will inform you about any issue the Agent encountered while interpreting your input.

static setIgnoreURLsByRegex([]String regexArray)

Parameters

Parameter
Description
regexArray An array of String objects containing the regex matching the URLs you want to ignore.

Returns: Promise(Boolean). In case of rejection, the exception contains a list of all the parameters that failed to be converted to native regex

Example

export default class App extends Component {
  componentDidMount() {
    setIgnoreURLsByRegex();
    async function setIgnoreURLsByRegex() {
      try {
        await Instana.setIgnoreURLsByRegex(["http:\/\/localhost:8081.*", "/.*([&?])password=.*/i"]);
      } catch (e) {
        console.warn(e);
      }
    }
  }

The example ignores all queries to the Metro bundler and all URLs that contain a password in the query.