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

For additional info please refer to the React Native Guide.

[!IMPORTANT] Starting the native SDK from JavaScript (sdkConfig.ios, sdkConfig.exporters) and @embrace-io/react-native-otlp are deprecated and will be removed in the next major release. Start Embrace in native code as described in Native Setup and Start Embrace SDK in the native side.

Requirements

Only an Embrace App ID and an Embrace API Token.

If you need an App ID and API Token, Go to our dashboard to create an account.

Integration

Add the JavaScript library

npm:

npm install @embrace-io/react-native

yarn:

yarn add @embrace-io/react-native

For iOS you will also need to install or update pods for the application:

cd ios && pod install --repo-update

Native Setup

There are 3 options for applying the native side changes required by the SDK: using our Expo config plugin, using our setup script, or applying them manually. Each options is described below.

Using the Expo config plugin

If you are using Expo's prebuild system to manage your native files you can make use of our config plugin. In your app.json configure the plugin with your Embrace application IDs and symbol upload API token:

    "plugins": [
        ...
        
        [
            "@embrace-io/react-native/lib/app.plugin.js",
            {
                "androidAppId": "__ANDROID_APP_ID__",
                "iOSAppId": "__IOS_APP_ID__",
                "apiToken": "__SYMBOL_UPLOAD_API_TOKEN__"
            }
        ]
    ],

Refer to EmbraceProps for the full set properties available to configure the plugin.

To source the Embrace iOS SDK from Swift Package Manager instead of CocoaPods, set the iOSUseSPM property. See Sourcing the Embrace iOS SDK from SPM below.

The next time you run npx expo prebuild the native Android and iOS files should be updated with the changes required by the Embrace SDK. Note that there are other customizations and advanced features of the SDK such as OTLP Export which will still require manual editing of native files, at the moment the config plugin only covers this initial SDK setup.

Running the setup scripts

The JavaScript Embrace SDK ships with a setup script to modify the files in your project to add the native dependencies. The setup scripts can be found in your node_modules folder at node_modules/@embrace-io/react-native/lib/scripts/setup.

node node_modules/@embrace-io/react-native/lib/scripts/setup/installAndroid.js

node node_modules/@embrace-io/react-native/lib/scripts/setup/installIos.js

Manually

To apply the native setup manually refer to this section of our guide to add the native SDKs, then follow the steps to start the Embrace SDK in the native side.

Sourcing the Embrace iOS SDK from SPM

By default the Embrace iOS SDK is installed as a CocoaPods dependency, but can be configured to source the iOS SDK from Swift Package Manager instead. SPM mode uses React Native's spm_dependency helper, which requires React Native >= 0.75 and USE_FRAMEWORKS=dynamic.

If you are using the Expo config plugin, set the iOSUseSPM property and add expo-build-properties with ios.useFrameworks: "dynamic", see the plugin's README for a full example.

Otherwise opt in when installing pods:

EMBRACE_USE_SPM=1 USE_FRAMEWORKS=dynamic pod install

Initialize the Embrace SDK

The Embrace SDK should be started in native code before initialize is called. The Expo config plugin and the setup scripts in Native Setup do this for you; if you set up manually, see Start Embrace SDK in the native side.

Then call initialize once, at the top level of your application, to set up tracking on the JS side:

import React, { useEffect } from 'react'
import { initialize } from '@embrace-io/react-native';

const App = () => {
  useEffect(() => {
    const initEmbrace = async () => {
      try {
        const isStarted = await initialize({ trackUnhandledRejections: true });

        if (isStarted) {
          // do something
        }
      } catch {
        console.log("Error initializing Embrace SDK");
      }
    };

    initEmbrace();
  }, []); // you should only initialize the Embrace SDK once.

  // regular content of the application
  return (
    ...
  );
}

export default App

Uploading source maps

The Embrace SDK allows you to view both native and JavaScript stack traces for crashes and error logs. Refer to our guide on uploading symbol files.

Additional features

Additional features for our SDK are kept in other packages to allow you to include just the dependencies for the ones you are using and to keep your overall bundle size smaller. Once this core package is installed you can check out the documentation in our Feature Reference to learn more about these additional packages. The various screens in our Test Harness also provide examples of how these packages can be used with the core SDK.

Troubleshooting

Please refer to our complete integration guide. If you continue to run into issues please contact us directly or reach out in our Community Slack