Skip to main content

Adding the Embrace SDK

Adding the React Native Embrace SDK​

Add the JavaScript library​

To add the JavaScript library to your React Native project, use one of the following commands.

npm:

npm install @embrace-io/react-native

yarn:

yarn add @embrace-io/react-native

Additionally, for iOS you will also need to install or update pods for the application regardless of npm or yarn:

cd ios && USE_FRAMEWORKS=dynamic pod install --repo-update
info

By default, pod install sources the Embrace Apple SDK from CocoaPods. To source it from Swift Package Manager (recommended) set EMBRACE_USE_SPM=1. See iOS dependency manager for more details.

info

Additional features for our SDK are kept in separate packages to allow you to include just the dependencies for the ones you wish to use and keep your overall bundle size smaller. The instructions on this page will add just our core SDK package as a dependency, additional packages can then be included later as you integrate more of the functionality described in our Feature Reference.

iOS dependency manager​

The Embrace React Native SDK supports sourcing native dependencies via Swift Package Manager (SPM) instead of CocoaPods from v7.1.0.

Currently this is opt-in, however we recommend switching now: the next major release will switch to using SPM by default, and subsequent releases will drop support for CocoaPods.

Requirements:

  • @embrace-io/react-native 7.1.0 or later, and the same version of every other @embrace-io/* package you use.
  • React Native 0.75.0 or later. Enabling SPM on earlier versions will fail with an explicit error during pod install.
  • Dynamic frameworks (USE_FRAMEWORKS=dynamic). Required for React Native's SPM interop support.

To opt in, add the embrace_post_install hook to your Podfile, and set EMBRACE_USE_SPM=1 before running pod install:

EMBRACE_USE_SPM=1 USE_FRAMEWORKS=dynamic pod install
info

On the first pod install with EMBRACE_USE_SPM=1 set, the embrace_post_install hook adds the SPM package refererence to the main app targetyour .pbxproj file, and keeps the version in sync with the React Native SDK on subsequent updates. These changes should be committed.

For bare React Native apps, re-running the iOS setup script will add the embrace_post_install hook to your Podfile. Or, alternatively, follow the manual setup guide.

For Expo apps, set "iOSUseSPM": true on our config plugin to apply the required changes during prebuild. You'll also need expo-build-properties with ios.useFrameworks: "dynamic".

CocoaPods​

CocoaPods is still the default. With EMBRACE_USE_SPM unset, pod install resolves the Embrace Apple SDK as the EmbraceIO pod and there is nothing extra to configure. Projects on CocoaPods will keep building after trunk goes read-only, but will not be able to upgrade to newer versions of the SDK.

To move back to CocoaPods from SPM, unset EMBRACE_USE_SPM and run pod install again (or set iOSUseSPM to false in the Expo config plugin). The embrace_post_install hook handles removing the package reference from your .pbxproj.

Native setup​

Choose from one of the following three methodologies for applying native changes to your application:

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__"
            }
        ]
    ],
info

Refer to EmbraceProps for the full set of 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.

Sourcing the Embrace iOS SDK from SPM​

By default the Embrace iOS SDK is installed as a CocoaPods dependency. To source it from Swift Package Manager instead, set iOSUseSPM and add expo-build-properties with ios.useFrameworks: "dynamic":

{
  "expo": {
    ...
    "plugins": [
      ["expo-build-properties", {"ios": {"useFrameworks": "dynamic"}}],
      [
        "@embrace-io/react-native/lib/app.plugin.js",
        {
          "androidAppId": "__ANDROID_APP_ID__",
          "iOSAppId": "__IOS_APP_ID__",
          "apiToken": "__SYMBOL_UPLOAD_API_TOKEN__",
          "iOSUseSPM": true
        }
      ],
      ...
    ],
    ...
  }
}
info

SPM mode uses React Native's spm_dependency helper, which requires Expo SDK 52 or later (React Native >= 0.75)

Setup script​

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.

Run the setup script

node node_modules/@embrace-io/react-native/lib/scripts/setup/installAndroid.js
node node_modules/@embrace-io/react-native/lib/scripts/setup/installIos.js
Clean Up Embrace implementation

If you need to clean up an Embrace implementation added manually or by our scripts you can use our uninstall script

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

You can use git to see the changes that the script made.

git diff

Compare the changes to the manual setup step to verify the changes were made correctly.

Manual Setup - iOS​

Configuration for iOS is handled in code when initializing the SDK which we will cover in the next step. The native module should be setup using Autolinking so you're good to go!

Apply the following changes to your Podfile:

Add the Embrace post_install hook​

The embrace_post_install hook keeps your app target's Embrace Swift Package Manager dependency in sync with the EMBRACE_USE_SPM flag. First, add the following to your Podfile to import the hook:

require Pod::Executable.execute_command('node', ['-p',
  'require.resolve(
    "@embrace-io/react-native/ios/scripts/embrace_post_install.rb",
    {paths: [process.argv[1]]},
  )', __dir__]).strip

then call it from your existing post_install block:

  post_install do |installer|
    react_native_post_install(
      installer,
      config[:reactNativePath],
      :mac_catalyst_enabled => false
    )

    # Adds/removes the app target's Embrace SPM dependencies based on the EMBRACE_USE_SPM flag
    embrace_post_install(installer)
  end
react-native-flipper is not supported​

KSCrash and react-native-flipper are NOT compatible. For React Native customers using 0.73 or before, react-native-flipper is included by default; for 0.74 onwards, it has been removed. If you have react-native-flipper in your project, you will need to disable it with the following changes to your react-native.config.js:

module.exports = {
  dependencies: {
    ...(process.env.NO_FLIPPER
      ? { 'react-native-flipper': { platforms: { ios: null } } }
      : {}),
  },
};

Manual Setup - Android​

Update the build.gradle file (usually located at <root>/android/build.gradle) to include the Embrace Gradle Plugin.

buildscript {
  repositories {
    mavenCentral()
    google()
  }
  dependencies {
    classpath "io.embrace:embrace-gradle-plugin:${findProject(':embrace-io_react-native').properties['emb_android_sdk']}"
  }
}

Then, update the app build.gradle file (usually located at <root>/android/app/build.gradle).

apply plugin: 'com.android.application'
apply plugin: 'io.embrace.gradle'
repositories {
  mavenCentral()
  google()
}

Now, add the Embrace config file at android/app/src/main/embrace-config.json, and add your API key and token. Make sure to also indicate that your app is using React Native.

{
  "app_id": "xxxxx",
  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "sdk_config": {
    "app_framework": "react_native"
  }
}
info

Your API ID and token are available on the Embrace dashboard.

info

You'll need to set the following permissions so the Embrace SDK can send events and monitor connectivity.

  • android.permission.INTERNET
  • android.permission.ACCESS_NETWORK_STATE

There's a little more configuration we have to do to set up the uploading of symbol files. You'll be learning about that next.

Troubleshooting​

Expo - Cannot find interface declaration for 'ModulesProvider'​

If you encounter the following build error on iOS after running through our setup using an expo app:

"Cannot find interface declaration for 'ModulesProvider', superclass of 'ExpoModulesProvider'"

Update your AppDelegate.m|mm file to include the following import, making sure it is added before your #import "ProjectName-Swift.h" line:

#import "ExpoModulesCore-Swift.h"

See this GitHub issue for more details.

Android build error on React Native 0.71​

In your android/app/build.gradle if you have

apply from react.gradle

try replacing it with:

apply plugin: "com.facebook.react"

See this commit for more details.

Package does not contain a valid config plugin​

Expo's plugin resolution method changed in version 52, the simplest way to guarantee our plugin is found across different Expo versions is to specify the full "@embrace-io/react-native/lib/app.plugin.js" path for the plugin in app.json rather just the "@embrace-io/react-native" package name. See this PR for more details.

EMBRACE_USE_SPM is set, but SPM support is not available​

Your React Native version predates spm_dependency, which was added in React Native 0.75. Either upgrade React Native or unset EMBRACE_USE_SPM and stay on CocoaPods.

Library not loaded: @rpath/...PackageProduct.framework at launch​

The Embrace framework resolved but was never embedded in the app bundle, usually because the embrace_post_install hook is missing from your Podfile's post_install block. Add it, run pod install again, and check that the EmbraceIO package product is listed under your app target's "Frameworks, Libraries, and Embedded Content". This often only shows up in Release builds — a Debug build can launch off an absolute path into DerivedData.

Swift Package Manager mode requires dynamic frameworks. Confirm pod install ran with USE_FRAMEWORKS=dynamic, or on Expo that expo-build-properties is configured with ios.useFrameworks: "dynamic", then reinstall pods. CocoaPods prints a warning during pod install when Swift packages are combined with static linking.

Embrace appears twice, or the wrong Apple SDK version resolves​

This usually means a leftover from switching dependency managers. Run pod install again with the embrace_post_install hook in place and EMBRACE_USE_SPM set the way you actually want it — the hook adds or removes the app target's package dependency to match, and re-pins the package to the Embrace Apple SDK version your @embrace-io/react-native version expects.