Upgrade guide

Upgrading to 7.1.0

Summary

No breaking changes, and no JavaScript API changes.
The pod 'KSCrash', :modular_headers => true Podfile line is no longer needed and can be removed.
New: you can source the Embrace Apple SDK from Swift Package Manager instead of CocoaPods. Opt-in for now, and recommended.

Upgrade to version 7.1.0 of the Embrace React Native packages by bumping the versions in your package.json and running npm install / yarn install.

Remove the KSCrash modular headers workaround

If your Podfile still contains this line, delete it:

# insert this line here to enable modular headers only for KSCrash
pod 'KSCrash', :modular_headers => true

This issue has been fixed upstream and is no longer required since 6.16.1. Re-running our setup or uninstall script, or an npx expo prebuild with our config plugin, removes it for you.

Add the Embrace `post_install` hook to your Podfile

Re-run our setup script or npx expo prebuild to pick this up, or add it by hand. The hook is required if you want to source the Embrace Apple SDK from Swift Package Manager, and harmless if you don't — with EMBRACE_USE_SPM unset it just removes anything an earlier Swift Package Manager install added.

Consider moving the Embrace Apple SDK to Swift Package Manager

CocoaPods trunk stops accepting new Podspecs on December 2, 2026. Your Podfile and the pod install step remain; only the Embrace Apple SDK dependency moves. It's opt-in in 7.1.0, but the next major release will use Swift Package Manager by default and subsequent releases will drop CocoaPods support, so switching now avoids doing it under time pressure later. See iOS dependency manager for requirements and setup.

Upgrading from 6.x to 7.x

Summary

The Embrace Android SDK has been updated from 7.x (v7.9.2) to 8.x (v8.4.0):
- New minimum version requirements for the JDK, Kotlin, Gradle, and AGP (see below).
- The embrace-swazzler Gradle plugin has been renamed to embrace-gradle-plugin.
No JavaScript API changes

The breaking changes in this release are Android-only. There are no JavaScript API changes.

The steps below outline the project configuration changes required for all React Native projects, however if you call the Embrace Android SDK directly from native code or use a custom swazzler {} Gradle DSL block, please review the Android Upgrade guide (7.x → 8.x) for full details of all breaking changes.

Update the Embrace packages

Upgrade to the latest 7.x versions of the Embrace React Native packages, either by bumping the versions in your package.json and running npm install / yarn install, or by removing the existing @embrace-io/* packages and reinstalling them.

Meet the new Android minimum versions

Embrace Android SDK 8.x raises the Minimum supported versions for Android build tooling. If you are using React Native 0.76 or lower, you may need to update your native Android configuration files. We recommend the following versions:

JDK 17
Kotlin 2.0.21+
Gradle 8.7+ *
AGP 8.6.0+ *

* For minSdk < 26 the minimum requirement is Gradle 8.4 and AGP 8.3.0, however we recommend using AGP 8.6.0+ / Gradle 8.7+ to avoid Kotlin metadata warnings emitted by the lint analyzer on older AGP versions.

info

Our React Native app templates contain a tested configuration for each supported React Native version that you may find useful as a guide for configuring your project.

Rename the Embrace Gradle plugin

The embrace-swazzler plugin artifact and plugin ID have been renamed. Update the references in your root android/build.gradle and android/app/build.gradle files:

Expo Config Plugin

If you are using our Expo config plugin you can simply re-run npx expo prebuild - the config plugin will apply the rename.

Setup script

Non-Expo users can re-run the setup script that ships with the SDK to apply the plugin rename:

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

Manual setup

Alternatively, you can update your Gradle files manually. In your root android/build.gradle, update the buildscript classpath:

// Before
classpath "io.embrace:embrace-swazzler:${findProject(':embrace-io_react-native').properties['emb_android_sdk']}"
// After
classpath "io.embrace:embrace-gradle-plugin:${findProject(':embrace-io_react-native').properties['emb_android_sdk']}"

In your android/app/build.gradle, update the applied plugin ID:

// Before
apply plugin: 'embrace-swazzler'
// After
apply plugin: 'io.embrace.gradle'

Remove the OpenTelemetry pin for `@embrace-io/react-native-otlp`

If you use the react-native-otlp package and previously added the OpenTelemetry resolutionStrategy block to your app's build.gradle outlined here you can now safely remove it. The underlying dependency conflict has been fixed upstream in the react-native-otlp package, so pinning the io.opentelemetry:* artifacts to 1.51.0 is no longer required.

Upgrading to 6.3.0

Summary

react-native-flipper is no longer supported for iOS builds.

Upgrade to version 6.3.0 of the Embrace React Native SDK packages by either updating the versions manually in your package.json and running yarn install or npm install, or by removing the existing packages and reinstalling them.

Embrace Apple SDK now depends on KSCrash

The Apple SDK now includes a dependency on KSCrash, which requires modular headers to build successfully. To support this Pod, update your Podfile by adding the following line before your target declaration:

# insert this line here to enable modular headers only for KSCrash
pod 'KSCrash', :modular_headers => true

target 'YourTargetName' do
  config = use_native_modules!
  flags = get_default_flags()

  use_react_native!(
    :path => config[:reactNativePath],
    ...

If you have `react-native-flipper` in your project

Disable the package for the iOS platform by updating your react-native.config.js:

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

Update your Embrace symbol upload build phase

Ensure your Embrace Symbol Uploads build phase matches the following:

REACT_NATIVE_MAP_PATH="$CONFIGURATION_BUILD_DIR/embrace-assets/main.jsbundle.map" EMBRACE_ID=__YOUR_5_DIGIT_ID__ EMBRACE_TOKEN=__YOUR_30_CHAR_TOKEN__ "$SRCROOT/../node_modules/@embrace-io/react-native/ios/scripts/run.sh"

Note: The upload scripts are now bundled with the @embrace-io/react-native package. They are no longer provided by the iOS native layer (before they were packed as part of the iOS Pods).
You can take a look at your node_modules and confirm that everything is there in node_modules/@embrace-io/react-native/ios/scripts.

Install the latest CocoaPods

Finally, install the latest CocoaPods with:

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

That’s it! Your application should now build successfully.

Upgrading to 6.2.1

Summary

Pin OpenTelemetry dependencies to 1.51.0 in your app's Gradle when using @embrace-io/react-native-otlp.

This version of the Embrace Android SDK pulls in transitive OpenTelemetry dependencies that cause an okhttp version conflict in React Native. When using react-native-otlp with this version, add the following resolutionStrategy block to your app's build.gradle to pin OpenTelemetry to 1.51.0:

configurations.all {
      resolutionStrategy {
          force("io.opentelemetry:opentelemetry-bom:1.51.0")
          force("io.opentelemetry:opentelemetry-api:1.51.0")
          force("io.opentelemetry:opentelemetry-sdk:1.51.0")
          force("io.opentelemetry:opentelemetry-context:1.51.0")
          force("io.opentelemetry:opentelemetry-exporter-otlp:1.51.0")
      }
  }

Note that this may require an upgrade to Java 17.

Upgrading from 5.x to 6.x

Summary

Removal or replacement of various packages and methods, see sections below for details on specific migrations
Initialization and configuration of the SDK on Android has been updated
Automatic support for CodePush has been removed
Unhandled promise rejection tracking is now opt-in

Upgrade to the latest 6.x versions of the Embrace React Native SDK packages by either bumping to the latest version manually in your package.json and running yarn install or npm install Or remove the existing packages entirely and re-installing.

Then install the latest Cocoapods with:

cd ios && pod update EmbraceIO && pod install --repo-update

Deprecated packages

Package	Comments
`@embrace-io/react-native-orientation-change-tracer`	Use `useOrientationListener` from `@embrace-io/react-native` instead.
`@embrace-io/react-native-web-tracker`	No longer supported.
`@embrace-io/react-native-spans`	Functionality has been moved to `@embrace-io/react-native-tracer-provider`.
`@embrace-io/react-navigation`	Functionality has been moved to `@embrace-io/react-native-navigation`.
`@embrace-io/react-native-apollo-graphql`	No longer supported.
`@embrace-io/react-native-action-tracker`	Functionality has been moved to `@embrace-io/react-native-redux`.

Removed APIs

Old API	Comments
`logScreen`	Use `addBreadcrumb(message: string)` instead.
`setUserAsPayer`	Use `addUserPersona("payer")` instead.
`clearUserAsPayer`	Use `clearUserPersona("payer")` instead.
`startView`	Interface changed and moved to the `@embrace-io/react-native-tracer-provider` package.
`endView`	No longer supported. Call `end()` on the span returned by `startView` instead.

Updating native initialization on Android

Specifying "react_native" as the app framework in the Android config is now required whereas previously only "app_id" and "app_token" were. To update edit android/app/src/main/embrace-config.json in your app so that it matches the following:

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

In addition, if you had previously run our install script or manually followed the steps for initializing the SDK from native code on Android you will have the following line in your MainApplication.java or MainApplication.kt:

Embrace.getInstance().start(this, false, Embrace.AppFramework.REACT_NATIVE)

Since the app's framework is now passed through the config JSON this invocation of start is no longer supported. To upgrade replace it with:

Embrace.getInstance().start(this)

Migrating traces

The @embrace-io/react-native-spans package has been removed and the functionality it provided is now available from the @embrace-io/react-native-tracer-provider package. The interface for interacting with spans has also been updated to conform to the OTel specification. To update, first switch your dependency to the new package and then migrate any method calls in your code that used the 5.x Traces methods to the updated methods as detailed in the 6.x Traces guide.

Migrating startView/endView calls

If you had previously been calling the startView and endView methods directly these have been moved from @embrace-io/react-native to @embrace-io/react-native-tracer-provider. You will need to set up that package and invoke startView using its updated signature as described in Track Components.

Migrating Redux actions instrumentation

If you had previously been using the buildEmbraceMiddleware method from the @embrace-io/react-native-action-tracker package this has been renamed and moved to @embrace-io/react-native-redux. You will need to set up that package and create the Embrace middleware using one of the updated methods as described in Track Redux Actions.

Navigation instrumentation was previously split into two separate packages (@embrace-io/react-navigation + @embrace-io/react-native-navigation) depending on which style of navigation was being instrumented. Now all navigation instrumentations resides in @embrace-io/react-native-navigation. To migrate please review the instructions on the Migrating from older versions section of the navigation feature page.

Removal of automated CodePush support

Previously our SDK would check if CodePush was integrated in the app and track OTA JS bundle updates for the purposes of keeping symbolication of stack traces consistent. Given the retirement of CodePush this functionality has been removed.

If your app uses OTA updates you can call setJavaScriptBundlePath(path: string) whenever a new bundle is available in order to have properly symbolicated stack traces. See Symbolication with OTA updates for more details.

Unhandled promise rejection tracking is now opt-in

Previously our SDK setup tracking for unhandled promise rejection tracking automatically. Now this feature must be explicitly enabled, see Report Unhandled Promise Rejections for more details.

Fixed process for uploading sourcemaps on iOS Expo apps

If your app is using Expo and you have previously followed our symbol file upload guide or ran our automated install script then please update your build phases with our latest instructions from Uploading Native And JavaScript Symbol Files to ensure that sourcemaps are uploaded correctly.

Upgrading from 4.x to 5.x

Summary

Moments have been removed, Traces should be used in their place
Configuration through Embrace-Info.plist on iOS has been removed, configuration is now done in code
Native side initialization of the Embrace SDK has been rewritten in Swift
Minimum versions for iOS deployment have been bumped (details here)
Minimum versions for Android Kotlin and AGP have been bumped (details here)

Upgrade to the latest 5.x versions of the Embrace React Native SDK packages by either bumping to the latest version manually in your package.json and running yarn install or npm install Or remove the existing packages entirely and re-installing.

Then install the latest Cocoapod with

cd ios && pod install --repo-update

SDK initialization and configuration is triggered in code

If you initialize the Embrace SDK in your JavaScript code it will need to be updated to include a sdkConfig parameter to configure the iOS SDK:

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

const App = ()=> {
  useEffect(() => {
    initialize({
      sdkConfig: {
        ios: {
          appId: "__APP_ID__",
        }
      }
    }).then(hasStarted => {
      if (hasStarted) {
         // do something
      }
    });
  }, []);

 return ...
}
export default App

Upgrade of native iOS code

The Embrace-Info.plist is no longer used for configuration and can be safely removed from your project.

Any existing initialization of the Embrace SDK that you had in your AppDelegate.m|mm|swift file should be removed. In Objective-c this would be a line such as:

[[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkReactNative];

Or in Swift a line such as:

Embrace.sharedInstance().start(launchOptions: launchOptions, framework:.reactNative)

Replace these with the updated initialization code outlined in Starting Embrace SDK from Android / iOS

Moments have been replaced by traces

APIs related to moments should be removed from your code.

Any place that you were previously instrumenting your app's performance using Moments can now be done using Performance Tracing, please refer to this guide for more information.

Troubleshooting

Android

The minimum version of AGP required for the Embrace Gradle Plugin to work as expected is 7.4.2. If an older version is used for building the React Native Android application it will still build successfully but the SDK won't be able to initialize properly, getting the following error in runtime even when everything is configured as expected:

Error occurred while initializing the Embrace SDK. Instrumentation may be disabled.
java.lang.IllegalStateException: Failed to load local config from resources.
	at io.embrace.android.embracesdk.internal.config.LocalConfigParser.fromResources(LocalConfigParser.kt:82)
	at io.embrace.android.embracesdk.internal.injection.ConfigModuleImpl.<init>(ConfigModuleImpl.kt:25)
	at io.embrace.android.embracesdk.internal.injection.ConfigModuleSupplierKt.createConfigModule(ConfigModuleSupplier.kt:31)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper$5.invoke(ModuleInitBootstrapper.kt:31)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper$5.invoke(ModuleInitBootstrapper.kt:31)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper$init$2$result$6.invoke(ModuleInitBootstrapper.kt:151)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper$init$2$result$6.invoke(ModuleInitBootstrapper.kt:150)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper.init(ModuleInitBootstrapper.kt:468)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper.init(ModuleInitBootstrapper.kt:150)
	at io.embrace.android.embracesdk.internal.injection.ModuleInitBootstrapper.init$default(ModuleInitBootstrapper.kt:114)
	at io.embrace.android.embracesdk.EmbraceImpl.startImpl(EmbraceImpl.kt:181)
	at io.embrace.android.embracesdk.EmbraceImpl.start(EmbraceImpl.kt:156)
	at io.embrace.android.embracesdk.Embrace.start(Embrace.java:106)
	at com.ensemble3.MainApplication.onCreate(MainApplication.java:56)
	at android.app.Instrumentation.callApplicationOnCreate(Instrumentation.java:1192)
	at android.app.ActivityThread.handleBindApplication(ActivityThread.java:6712)
	at android.app.ActivityThread.access$1300(ActivityThread.java:237)
	at android.app.ActivityThread$H.handleMessage(ActivityThread.java:1913)
	at android.os.Handler.dispatchMessage(Handler.java:106)
	at android.os.Looper.loop(Looper.java:223)
	at android.app.ActivityThread.main(ActivityThread.java:7656)
	at java.lang.reflect.Method.invoke(Native Method)
	at com.android.internal.os.RuntimeInit$MethodAndArgsCaller.run(RuntimeInit.java:592)
	at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:947)
Caused by: java.lang.IllegalArgumentException: No appId supplied in embrace-config.json. This is required if you want to send data to Embrace, unless you configure an OTel exporter and add embrace.disableMappingFileUpload=true to gradle.properties.
	at io.embrace.android.embracesdk.internal.config.LocalConfigParser.buildConfig(LocalConfigParser.kt:112)

The application will still work but the Embrace SDK won't initialize, causing unexpected issues. To resolve this please ensure you have the required minimum versions set in your Android build files (more details here)

Deprecated APIs

Old API	Comments
`endAppStartup`	Deprecated API that is no longer supported.
`startMoment`	Deprecated API that is no longer supported.
`endMoment`	Deprecated API that is no longer supported.
`getSessionProperties`	Deprecated API that is no longer supported.

Upgrade guide​

Upgrading to 7.1.0​

Remove the KSCrash modular headers workaround​

Add the Embrace post_install hook to your Podfile​

Consider moving the Embrace Apple SDK to Swift Package Manager​

Upgrading from 6.x to 7.x​

Update the Embrace packages​

Meet the new Android minimum versions​

Rename the Embrace Gradle plugin​

Expo Config Plugin​

Setup script​

Manual setup​

Remove the OpenTelemetry pin for @embrace-io/react-native-otlp​

Upgrading to 6.3.0​

Embrace Apple SDK now depends on KSCrash​

If you have react-native-flipper in your project​

Update your Embrace symbol upload build phase​

Install the latest CocoaPods​

Upgrading to 6.2.1​

Upgrading from 5.x to 6.x​

Deprecated packages​

Removed APIs​

Updating native initialization on Android​

Migrating traces​

Migrating startView/endView calls​

Migrating Redux actions instrumentation​

Migrating navigation instrumentation​

Removal of automated CodePush support​

Unhandled promise rejection tracking is now opt-in​

Fixed process for uploading sourcemaps on iOS Expo apps​

Upgrading from 4.x to 5.x​

SDK initialization and configuration is triggered in code​

Upgrade of native iOS code​

Moments have been replaced by traces​

Troubleshooting​

Android​

Deprecated APIs​

Upgrade guide

Upgrading to 7.1.0

Remove the KSCrash modular headers workaround

Add the Embrace `post_install` hook to your Podfile

Consider moving the Embrace Apple SDK to Swift Package Manager

Upgrading from 6.x to 7.x

Update the Embrace packages

Meet the new Android minimum versions

Rename the Embrace Gradle plugin

Expo Config Plugin

Setup script

Manual setup

Remove the OpenTelemetry pin for `@embrace-io/react-native-otlp`

Upgrading to 6.3.0

Embrace Apple SDK now depends on KSCrash

If you have `react-native-flipper` in your project

Update your Embrace symbol upload build phase

Install the latest CocoaPods

Upgrading to 6.2.1

Upgrading from 5.x to 6.x

Deprecated packages

Removed APIs

Updating native initialization on Android

Migrating traces

Migrating startView/endView calls

Migrating Redux actions instrumentation

Migrating navigation instrumentation

Removal of automated CodePush support

Unhandled promise rejection tracking is now opt-in

Fixed process for uploading sourcemaps on iOS Expo apps

Upgrading from 4.x to 5.x

SDK initialization and configuration is triggered in code

Upgrade of native iOS code

Moments have been replaced by traces

Troubleshooting

Android

Deprecated APIs