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

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.)

We require integrating both the native SDKs for iOS and Android. The native SDKs automatically grab information that are unavailable to the React Native layer. As such, you will be creating two separate AppIDs in Embrace - one for iOS and one for Android. The instructions below assume you will integrate both platforms.

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: Add the Native iOS and Android SDKs

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.
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. Run the following command in your terminal:
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 the SDK to your app by making the changes below to your project's build.gradle file. The file path is usually <YourReactNativeProject>/android/build.gradle.
buildscript {
  repositories {
    jcenter()
    google()
  }
  dependencies {
    classpath 'embrace-io:embrace-swazzler:3.4.1'
  }
}
  1. Add the following to your app/build.gradle file. The file path is usually <YourReactNativeProject>/android/app/build.gradle.
apply plugin: 'com.android.application'
apply plugin: 'embrace-swazzler'
repositories {
  jcenter()
  google()
}
embrace {
  // Replace with your APP_ID, which is a 5-character value, e.g. "aBc45" and the token
  appId = '<EMBRACE_APP_ID>'
  apiToken = '<API_TOKEN>'
}

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

Add compilation options for older React Native versions

React Native 0.59.0 and later automatically adds the required compileOptions directive to the android/app/build.gradle file. If you are using a version of React Native older than 0.59.0, or your project was created with a version older than 0.59.0, add the following to your android/app/build.gradle file:

android {
    ....

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
    ...
}

Embrace requires Android 4.1 (API 16) or later, Gradle 4.4, Android Build Tools Plugin 3.+ and Java 8. The AndroidManifest.xml should have android.permission.INTERNET and android.permission.ACCESS_NETWORK_STATE set so Embrace can send events and monitor connectivity. If you use a version older than any of those listed, please contact us via email or over Slack.

  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: "123")
clearUserIdentifier()

setUsername (username: "abc") 
clearUsername()

setUserEmail(userEmail: "user@example.com") 
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, and the native views are used to correlate OOMs, ANRs and Terminations last user action, and to display the path a user took within their timelines. logScreen sets a breadcrumb in the timeline for you to retrace the users steps.
// 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.