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.

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.

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 run the native setup steps manually refer to this section of our guide

Initialize the Embrace SDK

Without hooks

Calling the initialize method setups up the tracking for the SDK on the JS side. This is needed even if you choose to start the SDK earlier on the native side as explained below, however in that case the configuration passed through in the sdkConfig object is ignored in favor of the native startup configuration.

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

const App = () => {
  useEffect(() => {
    const initEmbrace = async () => {
      try {
        const isStarted = await initialize({
          sdkConfig: {
            ios: {
              appId: "abcdf",
            },
          },
        });

        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

With hooks

We expose also a hook that handles the initialization of Embrace in a more React friendly way:

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

const App = () => {
  // minimum of configuration required
  const {isPending, isStarted} = useEmbrace({
    ios: {
      appId: "__APP_ID__", // 5 digits string
    },
  });


  if (isPending) {
    return (
      <View>
        <Text>Loading Embrace</Text>
      </View>
    );
  } else {
    if (!isStarted) {
      console.log('An error occurred during Embrace initialization');
    }
  }

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

export default App

In both cases we recommend to use these methods to initialize the React Native Embrace SDK at the top level of your application just once to prevent side effects in the JavaScript layer.

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