The Embrace Developer Hub

Welcome to the Embrace documentation. You'll find comprehensive guides and documentation to help you start working with Embrace as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started

React Native Integration Guide

Welcome to the React Native Guide!

Embrace gathers the information that you need to identify issues and measure performance. The following React Native guide instructs on how to call the relevant functions so teams can speed up identification and diagnosis by providing much needed additional context to themselves (logs and user info) and measure the timing of key areas of their app explicitly (moments.)

Step 1: Installation of React Native via NPM

(If you do not use npm and would like to integrate directly via JS files, please refer to the Manual Integration instructions .)

Open your terminal and navigate to the root of your React Native project. Install the npm package by running the following command:

npm i -S react-native-embrace

Link the native modules with your React Native application:

react-native link react-native-embrace

Step 2: Integration of Native iOS and Android Components

Embrace collects a lot of data automatically to reduce your implementation steps. A few iOS and Android native steps are required to make the magic work correctly.

iOS Guide

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

  1. Add a single line to your Podfile. (The file is 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. Install the pod by going into the iOS project folder where the podfile is located, (generally inside of your React Native app directory,) and run:
pod install
  1. Initialize the Embrace SDK
    In the iOS project, find a file named AppDelegate.m, (which is usually located in <YourReactNativeProject>/ios/<YourAppName>/AppDelegate.m).
    Initialize the Embrace SDK as early as possible by placing 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

The APP_ID is available in the dashboard or by contacting Embrace at support@embrace.io.

Android Guide

  1. Add/confirm Android permissions for Embrace to send events by declaring permissions in your Android app's Manifest.
    Within the React Native app directory, find your app's AndroidManifest.xml file. (The file is usually located in <YourReactNativeProject>/android/app/src/main/AndroidManifest.xml.)
    Add/confirm the following 3 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>
  1. Add the SDK to your app by making 3 changes to your project's 'build.gradle' file. (The file is usually located in <YourReactNativeProject>/android/build.gradle.)
...
buildscript {
    repositories {
        jcenter() // Ensure this repository is specified
        ...
    }

    dependencies {
        classpath 'embrace-io:embrace-swazzler:3.3.1' // Add this line here
        ...
    }
}
...
allprojects {
    repositories {
        jcenter() // Ensure this repository is specified
        ...
    }
}
...
  1. In your app's `build.gradle file, add the following plugin and the Embrace API key and token:
apply plugin: 'com.android.application'
// Add this line on top of the file, right below the 'com.android.application'
apply plugin: 'embrace-swazzler' 
...
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
    }
    ...
}
...

The APP_ID and APP_TOKEN are available in the dashboard or by contacting Embrace at support@embrace.io.

  1. Initialize the Embrace client as early as possible so we can correctly track crashes, OOMs, ANRs and terminations. In the MainApplication.java class, add the following 2 lines. (The file is 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();
        ...
    }
    ...
}
  1. 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 a @StartupActivity annotation to the MainActivity.java so you can control the startup end time via React. (The file is usually located in <YourReactNativeProject>/android/app/src/main/java/com/<YourAppName>/MainActivity.java)
// Add this annotation
@StartupActivity
public class MainActivity extends ReactActivity {
    ...
}

Troubleshooting Note: During the linking process, React Native will add a line to your android app/build.gradle:

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

The compile instruction has been deprecated, but React Native still uses compile for the Linking process. If that line causes issues, replace compile with implementation:

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

Step 3: Call Methods for User Identifiers, Logs and Moments

Step 1: End Startup
The Startup 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 code below.

import {endAppStartup} from './embrace';

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

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

  • Identifying Users
    In order to correlate errors with customer reports, lookup a user, or see a list of users who experienced each error, set the User Identifier on startup and registration.
// 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()
  • Logging Breadcrumbs
    In order to understand what happened in your application before any issue, including a crash, leave short log statements. There is no limit and are visualized via the timeline of each session.
// Breadcrumbs: Log a Breadcrumb to display these on the User Timelines
logBreadcrumb(message: String)
  • Identifying Views
    Views are not automatically tracked within JS. Embrace auto detects those views that are native to iOS or Android. These views are used to correlate OOMs, ANRs and Terminations last user action, and to display the path a user took within their timelines.
// Views: Log a Screen as screens are not automatically detected when in JS
logScreen(screenName: String)
  • Set Moments (Start/Stop Timing)
    Moments are used to measure the length of time and user abandonment for key moments in your app. In general, moments are not interruptible by a user. Screenshots are taken when the user waits too long for a moment; for example, a spinner of death.
// 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>)
  • Set Errors, Warning and Info Logs
    Logs are used to identify errors or possible code issues. Think of them as developer self-help for context. Logs are aggregated, searchable, and viewed in the timeline. Often, logs contain screenshots and stacktraces.
//Logs : Logs are aggregated and searchable for insights and finding specific carts, users and other properties.

export const WARNING = 'warning';
export const INFO = 'info';
export const ERROR = 'error';

logMessage = (message: String, severity: 'info' | 'warning' | 'error' = 'error', properties: ?Dictionary<Any>)
  • Identify users in a segment
    A 'persona' is a categorization identifier of the user. Users can have one or more personas. Common personas include payers and new users. Please refer to the docs (Personas on iOS | Personas on Android) for categories available to set on a user.
// Personas : Include a user in a segment
// User personas are of specific types. For more info, please refer to the docs 
setUserPersona(persona: String)

clearUserPersona = (persona: String)

React Native Integration Guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.