@dynatrace/react-native-plugin

Dynatrace React Native Plugin

The Dynatrace React Native plugin enables you to manually- and auto-instrument your React Native app. It is compatible with raw, ejected React Native projects. It does not support Expo.

Requirements

• For Android users: Minimum SDK version 15
• For iOS users: Minimum iOS 6

Quick Setup

You have to follow three steps for the installation of the plugin:

• Installation of the plugin
• Configuration with Dynatrace
• Command for Instrumentation

Other Contents

• Manual Instrumentation
• Official documentation
• Troubleshooting and current restrictions
• Changelog
  
  

---

Installation of the plugin

1. react-native install @dynatrace/react-native-plugin or npm install @dynatrace/react-native-plugin
2. When using npm don't forget to call react-native link @dynatrace/react-native-plugin as well
3. Make the configuration by downloading dynatrace.config (See configuration)
4. If it is not ejected already, eject your ReactNative project using react-native eject in the terminal. This should give you iOS and Android folders.
5. Expo-Kit only: If you are using Expo the installation script propably was not triggered. Therfor you need to call it manually by running node ./node_modules/@dynatrace/react-native-plugin/scripts/install.js

Continue with the next step by configuring your application via Dynatrace so get a dynatrace.config file.

Manual Linking

If for some reason (seperate native projects) you can't use react-native link, you need to manually link them.

Manually iOS With CocoaPods support

insert the following in your Podfile:

pod 'react-native-dynatrace', :path => '../node_modules/@dynatrace/react-native-plugin'

Manually iOS Without CocoaPods support

• Open your project in Xcode
• Run open node_modules/@dynatrace/react-native-plugin/ios
• Drag DynatraceRNBridge.xcodeproj into your Libraries group
• Select your main project in the navigator to bring up settings
• Under Build Phases expand the Link Binary With Libraries header
• Scroll down and click the + to add a library
• Find and add libRNDynatrace.a under the Workspace group
• ⌘+B

Manually Android

• Edit android/app/build.gradle (note: app folder) to look like this: Apply our dynatrace.gradle in front of the react.gradle.

+ apply from: "../../node_modules/@dynatrace/react-native-plugin/files/dynatrace.gradle"
  apply from: "../../node_modules/react-native/react.gradle"

• Edit android/build.gradle to look like this: Include classpath 'com.dynatrace.tools:android:7.2.4.+' in the dependencies block.

dependencies {
+   classpath 'com.dynatrace.tools:android:7.2.4.+'
    classpath 'com.android.tools.build:gradle:3.3.1'
}

• Add DynatraceReactPackage to MainApplication:

package com.myapp;

+ import com.dynatrace.plugin.DynatraceReactPackage;

...
public class MainApplication extends Application implements ReactApplication {
  @Override
  protected List<ReactPackage> getPackages() {
      return Arrays.<ReactPackage>asList(
+		new DynatraceReactPackage(),
		new MainReactPackage()
      );
  }
}

Configuration with Dynatrace

If you want to instrument your React Native application just go to your Dynatrace WebUI and select the menu point "Deploy Dynatrace". Choose to setup mobile monitoring and select React Native Cordova (BETA). Afterwards it is possible for you to download the dynatrace.config file.

This file should be place in the root of your project (same place where the package.json/app.json is stored). If the file is not available the auto instrumentation will not work.

Example of a dynatrace.config file:

<NATIVEAGENT>
	<DTXApplicationID>Application ID</DTXApplicationID>
	<DTXAgentEnvironment>Agent Environment</DTXAgentEnvironment>
	<DTXClusterURL>Cluster URL</DTXClusterURL>
	<platform name="android">
		<DTXLogLevel>debug</DTXLogLevel>
	</platform>
	<platform name="ios">
		<DTXLogLevel>ALL</DTXLogLevel>
	</platform>
</NATIVEAGENT>

(BETA: Remove other parts from the dynatrace.config file besides the <NATIVEAGENT> tag)

In this example there are 3 different properties configured for the Mobile Agent. All properties which are available in the Mobile Agent can be used in the <NATIVEAGENT> tag. You can find all the available properties in the documentation of the mobile agent, see the documentation.

The properties DTXAgentEnvironment, DTXClusterURL and DTXApplicationID are defined as global properties (not within platform tag) and will therefore be applied to both platforms (Android and iOS). The property DTXLogLevel is set for the Android and iOS platform differently as their value is not the same. In general, all properties which are defined in a platform tag are overriding a duplicate global value. If for example DTXApplicationID is defined as a global property as well as an Android platform property, always the platform property will have a higher priority.

Command for Instrumentation

Use npm run instrumentDynatrace in the root of your React Native project (where you also find the package.json) - this will configure both Android and iOS project with the provided dynatrace.config.

This scripts assumes that the usual react native project structure is given. If not you can alter the command by passing several properties:

• gradle=C:\MyReactAndroidProject\build.gradle - Tell the script where the root build.gradle file is. We will assume that the other gradle file resides in /app/build.gradle. This will add the whole agent dependencies automatically for you and will update the configuration.
• plist=C:\MyReactIOSProject\projectName\info.plist - Tell the script where your info.plist file is. The plist file is used for updating the configuration for the agent.
• config=C:\SpecialFolderForDynatrace\dynatrace.config - If you have not got your config file in the root folder of the React Native project but somewhere else.

All this command can be appended to the command of npm run instrumentDynatrace

Manual Instrumentation

1. Import and initialize the bridge:

import { Dynatrace } from '@dynatrace/react-native-plugin';

1. Use manual instrumentation almost as you would in a native app. For example:

let myAction = Dynatrace.enterAction("MyButton tapped");
//Perform the action and whatever else is needed.
myAction.leaveAction();

1. You will notice that each method has an addition optional parameter platform of type String. You can use this to only trigger manual instrumentation for a specific OS. The available values are: ios, android and all.

If you provide any platform value, then the manual instrumentation call is passed to both iOS and Android. Otherwise it is passed only to the relevant OS. For example:

• Passing to iOS only:

let myAction = Dynatrace.enterAction("MyButton tapped", Dynatrace.PLATFORM_IOS);
//Perform the action and whatever else is needed.
myAction.leaveAction("ios"); 

• Passing to Android only:

let myAction = Dynatrace.enterAction("MyButton tapped", Dynatrace.PLATFORM_ANDROID);
//Perform the action and whatever else is needed.
myAction.leaveAction("android"); 

• Passing to both:

let myAction = Dynatrace.enterAction("MyButton tapped");
//Perform the action and whatever else is needed.
myAction.leaveAction(); 

API Documentation

Any documentation about the API can be found in the typings file which is in the typings/react-native-dynatrace.d.ts file.

Official documentation

• Android: https://www.dynatrace.com/support/help/setup-and-configuration/oneagent/android/
• iOS: https://www.dynatrace.com/support/help/setup-and-configuration/oneagent/ios/

Troubleshooting and current restrictions:

Basically if you have problems with the plugin please have a look into the logs. They will tell you what went wrong. The logs can be found in the plugins folder of your React Native project (usually node_modules/@dynatrace/react-native-plugin/logs).

• Missing property DTXApplicationID means that there is no configuration available. Are you sure you called npm run updateConfiguration at least once?
• Be aware if you change your project to pods when you already have installed the plugin, you will end up with duplicate symbols because of the already linked library. Remove the mdoule reference manually from your project.
  
  

---

Changelog

0.168.0

• Initial Beta Release