NPM - React Native Embrace

Embrace gathers the information needed to identify issues and measure performance automatically upon integration. The following React Native guide provides simple instruction on how to call the relevant functions so teams can be provided much needed additional context (logs and user info) and measure the timing of key areas of their app explicitly (moments).

For additional info please refer to the React Native Guide.

Requirements

Only an Embrace App ID and an Embrace API Token.

If you need an App ID and API Token, contact us at [email protected] or on Slack.

Integration

Step 1: Add Native Embrace iOS SDK

1.1: Add EmbraceIO's Pod to your Podfile

The Embrace SDK is available through CocoaPods. If you do not use CocoaPods, follow the instructions here, on the step Configuring CocoaPods dependencies.

Add the Embrace.io pod to your Podfile: (usually located in YourReactNativeProject/ios/Podfile).

target 'YourApp' do
    ...
    pod 'React', :path => '../node_modules/react-native', :subspecs => [
        'Core',
        'CxxBridge',
        'DevSupport',
        'RCTText',
        'RCTNetwork',
        'RCTWebSocket',
        'RCTAnimation'
    ]

    # Add this line in the end of the target block
    pod 'EmbraceIO'

end

1.2: Install the Pods

Go into the iOS project folder inside of your React Native app directory, where the Podfile should be located, and on your terminal run:

$ pod install

1.3: Initialize the SDK

On the iOS project, you'll find a file named AppDelegate.m. (usually located in YourReactNativeProject/ios/YourAppName/AppDelegate.m).

To initialize the Embrace SDK as early as possible, we strongly recommend that you place the Embrace start call on the first line of your application:didFinishLaunchingWithOptions callback.

#import "AppDelegate.h"
#import <React/RCTBundleURLProvider.h>
#import <React/RCTRootView.h>
#import <Embrace/Embrace.h> // Remember to add the import line

@implementation AppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions
{
    // Replace with your APP_ID, which is a 5-character value, e.g. "aBc45"
    [[Embrace sharedInstance] startWithKey:@"APP_ID"];
    ...
    return YES;
}

@end

Optional:

This is a simplified process for React Native projects. If you want further information on the iOS SDK integration, you can check the steps on the Native iOS Quick Integration Guide.

Step 2: Add Native Embrace Android SDK

2.1: Add Android Permissions

Your application must have access to the internet to send events. In order to do so, you must declare permissions in you Android app's Manifest.

Into the android project folder inside of your React Native app directory, look for your app's AndroidManifest.xml file. (usually located in YourReactNativeProject/android/app/src/main/AndroidManifest.xml).

Add the following lines inside of the <manifest> tag in the AndroidManifest.xml file.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.myReactNativeProject">

    <!--ADD THESE TWO LINES WITH THE REST OF THE PERMISSIONS-->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <!-- // -->

    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"/>

    <application
      android:name=".MainApplication"
      ...
    </application>

</manifest>

2.2: Add the SDK to your app

The Embrace Android SDK is publicly available on Maven Central. To add it to your app, simply make the following changes in your projects’s build.gradle file: (usually located in YourReactNativeProject/android/build.gradle).

...
buildscript {
    repositories {
        mavenCentral() // Ensure this repository is specified
        ...
    }

    dependencies {
        classpath 'io.embrace:embrace-swazzler:5.5.2' // Add this line here
        ...
    }
}
...
allprojects {
    repositories {
        mavenCentral() // Ensure this repository is specified
        ...
    }
}
...

Then in your app's build gradle file: (usually located in YourReactNativeProject/android/app/build.gradle).

apply plugin: 'com.android.application'
// Add this line on top of the file, right below the 'com.android.application' one
apply plugin: 'embrace-swazzler'

Also, inside the android block in the same file:

...
android {
    ...
    embrace {
        // Replace with your APP_ID, which is a 5-character value, e.g. "aBc45" and the token
        appId = '<APP_ID>'
        apiToken = '<APP_TOKEN>'
    }
    compileOptions {
        // If compile options is not present, add it.
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    ...
}
...

2.3: Initialize the SDK

Initialize the Embrace client as early as possible so we can correctly track crashes, OOMs, ANRs and termination. Open the MainApplication.java class and add the following lines: (usually located in YourReactNativeProject/android/app/src/main/java/com/YourAppName/MainApplication.java).

import io.embrace.android.embracesdk.Embrace; // Add the import line

public class MainApplication extends Application implements ReactApplication {

    ...

    @Override
    public void onCreate() {
        super.onCreate();
        Embrace.getInstance().start(this); // Add this line right after the super.onCreate();
        ...
    }
    ...
}

2.4: Define the App Startup

Embrace automatically detects the beginning and end of the Startup. However, since Startups end in multiple ways - a deep link to a particular activity, a load of a home screen, a promotion, you must explicitly define which activities do not constitute the end of a Startup.

Add @StartupActivity annotation to the MainActivity.java if you want to handle the startup end time: (usually located in YourReactNativeProject/android/app/src/main/java/com/YourAppName/MainActivity.java).

// Add this annotation
@StartupActivity
public class MainActivity extends ReactActivity {
    ...
}

Optional:

This is a simplified process for React Native projects. If you want further information on the Android SDK integration, you can check the steps on the Native Android Quick Integration Guide.

Step 3: Add the embrace-react-native npm package to your React Native Project

In order to access the native functionalities that the Embrace SDKs provide, we built a wrapper using an npm package, fully compatible with react-native linking logic. Open your terminal and on the root of your React Native project install the npm package by running the following:

$ npm i -S react-native-embrace

Step 4: Link react-native-embrace

React Native offers a pretty handy command that automatically links native modules with you React Native application. For more info, you can get it on the Original Documentation Site.

To link embrace-react-native, open your terminal and on your React Native project root run:

$ react-native link react-native-embrace

Troubleshoot Step - Deprecated instruction on you app's build gradle file.

During the linking process, React native will add a line to your android app/build.gradle file like this:

...
compile project(':react-native-embrace')

Be aware that the compile instruction has been deprecated but React Native still uses it on the Linking process. If that line is causing issues, you can replace it with:

...
implementation project(':react-native-embrace')

implementation is the right instruction for the compiler to add dependency to the project. You can read more about this here

Step 5: Install latest pods

Once you're done linking, it's necessary to download the pods that were linked to the project. To do so, go into the iOS project folder inside of your React Native app directory, where the Podfile should be located, and run:

$ pod install

This should download RNEmbrace pod to your iOS Project.

Step 6: Call Methods

A good place to start is after your startup moment ends. This moment starts automatically with the code added to AppDelegate.m on iOS or MainActivity.java on Android, and you should end on Component mount similar to the below code.

import { endAppStartup } from "react-native-embrace";

type Props = {};
export default class App extends Component<Props> {
  componentDidMount() {
    endAppStartup();
  }
}

Step 7: Integrate the User Identifier, Logs and Moments into your App

Since React Native is built with either an iOS or Android native framework, most of the functionality integrated to effectively use Embrace can be called either in Swift / Obj-C, Java, or Javascript. Please follow the iOS Quick Integration or Android Quick Integration for the remaining steps to complete your integration.

The following calls located in the file, embrace.js, are listed below for reference.

// Startup: Call each place a startup may conclude.  Remember those deeplinks!
endAppStartup(properties: ?Dictionary<Any>)

// User Identifiers: Set (or clear) one or more User Identifiers on app start up or registration
setUserIdentifier(userIdentifier: String)
clearUserIdentifier()

setUsername (username: String)
clearUsername()

setUserEmail(userEmail: String)
clearUserEmail()

setUserAsPayer()
clearUserAsPayer()
// Breadcrumbs: Log a Breadcrumb to display these on the User Timelines
logBreadcrumb(message: String)

// Views: Log a Screen as screens are not automatically detected when in JS
logScreen(screenName: String)

// Moments : Start and End a Moment.
// For ex, a purchase is from click-to-purchase to both success or failure
// For more information on Moments, please refer to the docs in the links below

startMoment(name: String, identifier: ?String, properties: ?Dictionary<Any>)

startMomentAllowingScreenshot (name: String, allowScreenshot: Boolean, identifier: ?String, properties: ?Dictionary<Any>)

endMoment(name: String, identifier: ?String, properties: ?Dictionary<Any>)

//Logs : Logs are aggregated and searchable for insights and finding specific carts, users and other properties.
//Logs are sent immediately to assure effective replays of problematic sessions
export const WARNING = 'warning';
export const INFO = 'info';
export const ERROR = 'error';

logMessage = (message: String, severity: 'info' | 'warning' | 'error' = 'error', properties: ?Dictionary<Any>)

// Personas : Include a user in a segment
// User personas are of specific types. For more info, please refer to the docs in the links below
setUserPersona(persona: String)
clearUserPersona(persona: String)

//Custom Views :  specify views that will be displayed in the dashboard
startView(view: string)
endView (view: string)

//Session Properties :  specify properties for your sessionsgit
addSessionProperty(key: string, value: string, permanent: boolean)
removeSessionProperty(key: string)
getSessionProperties()

// Manual session ending: remember to check your embrace-config file to enable it.
endSession = (clearUserInfo: boolean = false)