Embrace React Native

https://embrace.io/docs/react-native/
Admin
Embrace React Native SDK is an observability platform that provides performance monitoring, crash...
Tokens:17,486
Snippets:217
Trust Score:9.9
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Tracer Provider Package

Source: https://embrace.io/docs/react-native/features/traces

Commands to install the required tracer provider package using npm or yarn.

```bash
npm install @embrace-io/react-native-tracer-provider
```

```bash
yarn add @embrace-io/react-native-tracer-provider
```

--------------------------------

### Install OTLP Package

Source: https://embrace.io/docs/react-native/features/otlp

Commands to install the OTLP package using npm or yarn.

```bash
npm install @embrace-io/react-native-otlp
```

```bash
yarn add @embrace-io/react-native-otlp
```

--------------------------------

### Install navigation package

Source: https://embrace.io/docs/react-native/features/navigation

Commands to install the navigation tracking package via npm or yarn.

```bash
npm install @embrace-io/react-native-navigation
```

```bash
yarn add @embrace-io/react-native-navigation
```

--------------------------------

### Install latest CocoaPods

Source: https://embrace.io/docs/react-native/upgrading

Run this command to install the latest CocoaPods with dynamic framework support.

```bash

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



```

--------------------------------

### Setup EmbraceNavigationTracker with @react-navigation/native

Source: https://embrace.io/docs/react-native/features/navigation

Implementation example for integrating navigation tracking with @react-navigation/native, requiring a ref recreation.

```javascript
import React, { useRef } from 'react';  

import { useEmbraceNativeTracerProvider } from '@embrace-io/react-native-tracer-provider';  

import { EmbraceNavigationTracker } from '@embrace-io/react-native-navigation';  

import {  

  NavigationContainer,  

  useNavigationContainerRef,  

} from '@react-navigation/native';  

import { useEmbrace } from '@embrace-io/react-native';  

  

const App = () => {  

  const { isPending, isStarted } = useEmbrace({  

    ios: {  

      appId: '__APP_ID__',  

    },  

  });  

  

  const { tracerProvider, isLoading: isLoadingTracerProvider } =  

    useEmbraceNativeTracerProvider({}, isStarted);  

  

  // as of now if you inspect the source code of `useNavigationContainerRef` from `@react-navigation/native` you will see that it returns `navigation.current` instead of the entire shape of a reference  

  const navigationRefVal = useNavigationContainerRef();  

  // We need here the entire shape, so we re-create it and pass it down into the `ref` prop for the `EmbraceNavigationTracker` component.  

  const navigationRef = useRef(navigationRefVal);  

  

  if (isLoadingTracerProvider) {  

    return (  

      <View>  

        <Text>Loading Tracer Provider...</Text>  

      </View>  

    );  

  }  

  

  return (  

    // `NavigationContainer` is waiting for what `useNavigationContainerRef` is returning (both exported from `@react-navigation/native`)  

    <NavigationContainer ref={navigationRefVal}>  

      <EmbraceNavigationTracker  

        ref={navigationRef}  

        tracerProvider={tracerProvider}  

        screenAttributes={{  

          'static.attribute': 123456,  

          'custom.key': 'custom.value',  

        }}>  

        {/* rest of the navigation */}  

      </EmbraceNavigationTracker>  

    </NavigationContainer>  

  );  

};  

  

export default App;
```

--------------------------------

### Run Setup Scripts

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Execute the provided scripts to automatically modify native files for Android or iOS.

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

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

--------------------------------

### Setup EmbraceNavigationTracker with expo-router

Source: https://embrace.io/docs/react-native/features/navigation

Implementation example for integrating navigation tracking with expo-router.

```javascript
import React from 'react';  

import { View, Text } from 'react-native';  

import { useEmbraceNativeTracerProvider } from '@embrace-io/react-native-tracer-provider';  

import { EmbraceNavigationTracker } from '@embrace-io/react-native-navigation';  

import { useNavigationContainerRef } from 'expo-router';  

import { useEmbrace } from '@embrace-io/react-native';  

  

const App = () => {  

  const { isPending, isStarted } = useEmbrace({  

    ios: {  

      appId: '__APP_ID__',  

    },  

  });  

  

  // make sure a tracer provider is registered BEFORE you attempt to record the first span (otherwise some initial telemetry can be missed).  

  const { tracerProvider, isLoading: isLoadingTracerProvider } =  

    useEmbraceNativeTracerProvider({}, isStarted);  

  

  const expoNavigationRef = useNavigationContainerRef();  

  

  if (isLoadingTracerProvider) {  

    return (  

      <View>  

        <Text>Loading Tracer Provider...</Text>  

      </View>  

    );  

  }  

  

  return (  

    <EmbraceNavigationTracker  

      ref={expoNavigationRef}  

      tracerProvider={tracerProvider}  

      // These static attributes will be passed into each created span  

      screenAttributes={{  

        'static.attribute': 123456,  

        'custom.key': 'custom.value',  

      }}>  

      {/* rest of the navigation */}  

    </EmbraceNavigationTracker>  

  );  

};  

  

export default App;
```

--------------------------------

### Verify Changes with Git

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Check the modifications made by the setup scripts using git diff.

```bash
git diff
```

--------------------------------

### Run the Embrace Android Setup Script

Source: https://embrace.io/docs/react-native/upgrading

Execute this script to automatically apply the Embrace Gradle plugin rename for non-Expo projects.

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

--------------------------------

### Implement OTLP Export

Source: https://embrace.io/docs/react-native/features/otlp

Example of configuring the Embrace SDK with OTLP exporters for log and trace data.

```javascript
import React, { useEffect, useMemo, useState } from 'react';  

import { useEmbrace } from '@embrace-io/react-native';  

import { View, Text } from 'react-native';  

import { Stack } from 'expo-router';  

  

const GRAFANA_TOKEN = '__GRAFANA_TOKEN__'; // `grafana_instance:token` converted into a base64 string.  

const EXPORTER_CONFIG = {  

  logExporter: {  

    endpoint: 'https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/logs',  

    headers: [  

      {  

        key: 'Authorization',  

        token: `Basic ${GRAFANA_TOKEN}`,  

      },  

    ],  

  },  

  traceExporter: {  

    endpoint:  

      'https://otlp-gateway-prod-us-central-0.grafana.net/otlp/v1/traces',  

    headers: [  

      {  

        key: 'Authorization',  

        token: `Basic ${GRAFANA_TOKEN}`,  

      },  

    ],  

  },  

};  

  

// iOS is configurable through code, Android configuration happens at build time  

const IOS_SDK_CONFIG = { appId: '__APP_ID__' };  

  

function RootLayout() {  

  const { isPending, isStarted } = useEmbrace({  

    ios: IOS_SDK_CONFIG,  

    exporters: EXPORTER_CONFIG,  

  });  

  

  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 (  

    <Stack>  

      <Stack.Screen name="(tabs)" options={{ headerShown: false }} />  

    </Stack>  

  );  

}  

  

export default RootLayout;
```

--------------------------------

### Uninstall Embrace Implementation

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Use the uninstall script to revert changes made by the setup scripts.

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

--------------------------------

### Example Stack Trace with Unknown Entries

Source: https://embrace.io/docs/react-native/features/render-errors

A sample of a stack trace in release builds where some view names could not be retrieved.

```text

 * in Unknown  

 * in RCTView  

 * in Unknown  

 * in AppContainer  



```

--------------------------------

### tracer.startSpan(name, options)

Source: https://embrace.io/docs/react-native/features/traces

Starts a new span with an optional configuration object including startTime and attributes.

```APIDOC
## tracer.startSpan(name, options)

### Description
Creates a new span for tracking operations. You can optionally provide a startTime or initial attributes.

### Parameters
- **name** (string) - Required - The name of the span.
- **options** (object) - Optional - Configuration object containing `startTime` (number) or `attributes` (object).
```

--------------------------------

### Install iOS Pods

Source: https://embrace.io/docs/react-native/features/otlp

Command to update iOS pods for the application.

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

--------------------------------

### Install Redux telemetry package

Source: https://embrace.io/docs/react-native/features/redux-actions

Commands to install the required Redux integration package using npm or yarn.

```bash
npm install @embrace-io/react-native-redux
```

```bash
yarn add @embrace-io/react-native-redux
```

--------------------------------

### Update Android SDK Initialization

Source: https://embrace.io/docs/react-native/upgrading

Replace the legacy start method call in MainApplication with the simplified version.

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

```java
Embrace.getInstance().start(this)
```

--------------------------------

### Example Component Stack Trace

Source: https://embrace.io/docs/react-native/features/render-errors

A sample of the component stack trace logged by the SDK when a rendering error occurs.

```text

 * in Screen2  

 * in RCTView  

 * in Screen1  

 * in AppContainer  



```

--------------------------------

### Install Embrace SDK via Package Manager

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Use npm or yarn to add the core Embrace SDK package to your project.

```bash
npm install @embrace-io/react-native
```

```bash
yarn add @embrace-io/react-native
```

--------------------------------

### Start Span with Custom Timestamp

Source: https://embrace.io/docs/react-native/features/traces

Initialize a span with a specific start time.

```javascript
const span = tracer.startSpan('span-name', {  

  startTime: new Date().getTime(),  

});
```

--------------------------------

### Initialize Embrace in Android MainApplication

Source: https://embrace.io/docs/react-native/integration/session-reporting

Start the Embrace SDK within the onCreate method of the MainApplication class for Android.

```kotlin
import io.embrace.android.embracesdk.Embrace  

  

...  

  

class MainApplication : Application(), ReactApplication {  

  override fun onCreate() {  

    super.onCreate()  

  

    // Add this line right after the super.onCreate()  

    Embrace.start(this)  

  }  

}  
```

```java
import io.embrace.android.embracesdk.Embrace;  

  

...  

  

public class MainApplication extends Application implements ReactApplication {  

  

    @Override  

    public void onCreate() {  

        super.onCreate();  

  

        // Add this line right after the super.onCreate();  

        Embrace.INSTANCE.start(this);  

    }  

}  
```

--------------------------------

### Create EmbraceInitializer for iOS

Source: https://embrace.io/docs/react-native/integration/session-reporting

Define a Swift class to handle the Embrace SDK setup. Note that parameters passed via JavaScript's sdkConfig.ios will be ignored when using this method.

```swift
import Foundation  

import EmbraceIO  

  

@objcMembers class EmbraceInitializer: NSObject {  

    static func start() -> Void {  

        do {  

            try Embrace  

                .setup(  

                    options: Embrace.Options(  

                        appId: "__APP_ID__", // 5 digits string  

                        platform: .reactNative  

                    )  

                )  

                .start()  

        } catch let e {  

            print("Error starting Embrace \(e.localizedDescription)")  

        }  

    }  

}  
```

--------------------------------

### Configure Expo Plugin

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Add the Embrace plugin to your app.json to automate native setup during prebuild.

```json
"plugins": [  

        ...  

  

        [  

            "@embrace-io/react-native/lib/app.plugin.js",  

            {  

                "androidAppId": "__ANDROID_APP_ID__",  

                "iOSAppId": "__IOS_APP_ID__",  

                "apiToken": "__SYMBOL_UPLOAD_API_TOKEN__"  

            }  

        ]  

    ],
```

--------------------------------

### Initialize Embrace SDK with hooks

Source: https://embrace.io/docs/react-native/integration/session-reporting

Use the useEmbrace hook for a more React-friendly initialization process. This hook manages the pending and started states of the SDK.

```javascript
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
```

--------------------------------

### Initialize Embrace in Swift AppDelegate

Source: https://embrace.io/docs/react-native/integration/session-reporting

Call the initializer at the start of the application launch method in a Swift-based AppDelegate.

```swift
@UIApplicationMain  

class AppDelegate: UIResponder, UIApplicationDelegate {  

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {  

        EmbraceInitializer.start()  

  

        // rest of the logic  

    }  

}  
```

--------------------------------

### Track component duration with startView

Source: https://embrace.io/docs/react-native/features/components

Use startView to create a span that tracks the duration of a component's lifecycle. Requires a tracer instance obtained from the Traces guide.

```javascript
import { startView } from '@embrace-io/react-native-tracer-provider';  

  

const viewSpan = startView(tracer, 'MyView');  

  

// ...at some later point...  

viewSpan.end();
```

--------------------------------

### getDeviceId()

Source: https://embrace.io/docs/react-native/features/session-metadata

Retrieves the unique device ID associated with the current installation.

```APIDOC
## getDeviceId()

### Description
Retrieves the unique device ID for the current device.

### Signature
`getDeviceId(): Promise<string>`

### Usage
```javascript
import { getDeviceId } from '@embrace-io/react-native';

getDeviceId().then((deviceId) => {
  console.log('Embrace Device Id', deviceId);
});
```
```

--------------------------------

### Update CocoaPods for 6.x migration

Source: https://embrace.io/docs/react-native/upgrading

Update the EmbraceIO pod and install dependencies during the migration from 5.x to 6.x.

```bash

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



```

--------------------------------

### Disable automatic view capture on iOS

Source: https://embrace.io/docs/react-native/features/navigation

Remove the view capture service in your EmbraceInitializer.swift file during SDK setup.

```swift
import Foundation
import EmbraceIO
import KSCrash

@objcMembers class EmbraceInitializer: NSObject {
    static func start() -> Void {
        do {

            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "__APP_ID__",
                        platform: .reactNative,
                        captureServices: CaptureServiceBuilder()
                            .addDefaults()
                            .remove(ofType: ViewCaptureService.self)
                            .build(),
                        crashReporter: KSCrashReporter()
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}
```

--------------------------------

### Android Initialization Error Log

Source: https://embrace.io/docs/react-native/upgrading

Runtime error indicating an incompatible AGP version or missing configuration.

```text
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)
```

--------------------------------

### Define Embrace Configuration

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Create the embrace-config.json file with your app ID and token.

```json
{

  "app_id": "xxxxx",

  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "sdk_config": {

    "app_framework": "react_native"

  }

}  
```

--------------------------------

### Initialize Embrace SDK without hooks

Source: https://embrace.io/docs/react-native/integration/session-reporting

Use the initialize method to set up SDK tracking on the JavaScript side. This should be called only once at the top level of the application.

```javascript
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();  

  }, []); // Empty array for mount only in example; you should only initialize the Embrace SDK once.  

  

  // regular content of the application  

  return (  

    ...  

  );  

}  

  

export default App
```

--------------------------------

### Upload OTA update source maps

Source: https://embrace.io/docs/react-native/integration/upload-symbol-files

Manually upload source maps for over-the-air updates using the Embrace CLI tool.

```bash
# For macOS, use arch "darwin", for Linux use "linux.arm64" or "linux.amd64" (depending on your CPU)  

node_modules/@embrace-io/react-native/ios/scripts/embrace_symbol_upload.<arch> --app <your app ID> --token <your token> --rn-bundle path/to/main.jsbundle --rn-map path/to/main.jsbundle.map
```

--------------------------------

### Analyze Bundle Size

Source: https://embrace.io/docs/react-native/features/render-errors

Command to generate a production bundle to verify the impact of Metro configuration changes on bundle size.

```bash

npx react-native bundle \

  --platform <platform> \

  --dev false \

  --entry-file index.js \

  --bundle-output ./output/main.bundle.js \

  --assets-dest ./output  



```

--------------------------------

### Initialize screen orientation tracking

Source: https://embrace.io/docs/react-native/features/screen-orientation

Invoke the hook after Embrace initialization to automatically log orientation change breadcrumbs.

```javascript
import { useOrientationListener } from '@embrace-io/react-native-orientation-change-tracker';  

  

useOrientationListener();
```

--------------------------------

### Initialize Embrace in Objective-C AppDelegate

Source: https://embrace.io/docs/react-native/integration/session-reporting

Import the generated Swift header and call the initializer in the application launch method for Objective-C projects.

```objective-c
#import "AppDelegate.h"  

#import "ProductModuleName-Swift.h"  

  

...  

  

@implementation AppDelegate  

  

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions  

{  

  [EmbraceInitializer start];  

  

  // rest of the logic  

}  
```

--------------------------------

### Configure Podfile for KSCrash

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Enable modular headers for KSCrash in your iOS Podfile.

```ruby
# insert this line here to enable modular headers only for KSCrash  

pod 'KSCrash', :modular_headers => true  

  

target 'ProjectName' do  

  config = use_native_modules!  

  flags = get_default_flags()  

  

  use_react_native!(  

    :path => config[:reactNativePath],  

    ...
```

--------------------------------

### Configure Root build.gradle for Embrace

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Add the Embrace Gradle plugin dependency to the root build.gradle file.

```gradle
buildscript {  

  repositories {  

    mavenCentral()  

    google()  

  }  

  dependencies {  

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

  }  

}  
```

--------------------------------

### Initialize Tracer Provider

Source: https://embrace.io/docs/react-native/features/traces

Use the useEmbraceNativeTracerProvider hook to obtain a tracer instance after the Embrace SDK has successfully initialized.

```javascript
import { useEmbraceNativeTracerProvider } from '@embrace-io/react-native-tracer-provider';  

import { useEmbrace } from '@embrace-io/react-native';  

  

const { isPending, isStarted } = useEmbrace({  

  ios: {  

    appId: '__APP_ID__',  

  },  

});  

  

if (isPending) {  

  return (  

    <View>  

      <Text>Loading Embrace</Text>  

    </View>  

  );  

} else {  

  if (!isStarted) {  

    console.log('An error occurred during Embrace initialization');  

  }  

}  

  

const { tracer } = useEmbraceNativeTracerProvider({}, isStarted);
```

--------------------------------

### Implement legacy navigation tracking with useEmbraceNavigationTracker

Source: https://embrace.io/docs/react-native/features/navigation

Uses the older hook-based approach to track navigation by passing a ref to the NavigationContainer.

```javascript
import {useRef} from 'react'  

import {useEmbraceNavigationTracker} from '@embrace-io/react-navigation';  

  

function App() {  

  // Create the reference  

  const navigationRef = useRef();  

  // Pass the reference to Embrace's Hook  

  useEmbraceNavigationTracker(navigationRef);  

  

  return (  

    // Assign the NavigationContainer reference value to the useRef created  

    <NavigationContainer ref={navigationRef}>  

      <Screens... />  

    </NavigationContainer>  

  );  

}  
```

--------------------------------

### Initialize Embrace SDK in React Native

Source: https://embrace.io/docs/react-native/upgrading

Update the SDK initialization to include the sdkConfig parameter for iOS configuration.

```javascript
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
```

--------------------------------

### Track navigation with react-native-navigation

Source: https://embrace.io/docs/react-native/features/navigation

Wrap entry views with EmbraceNativeNavigationTracker and initialize the SDK early to ensure telemetry data is captured.

```typescript
// index.ts  

import React, {useRef} from "react";  

import {EmbraceNativeTracerProvider} from "@embrace-io/react-native-tracer-provider";  

import {TracerProvider} from "@opentelemetry/api";  

import {EmbraceNativeNavigationTracker} from "@embrace-io/react-native-navigation";  

import {initialize} from "@embrace-io/react-native";  

import {Navigation} from "react-native-navigation";  

import {HomeScreen} from "screens/HomeScreen";  

  

const initApp = async () => {  

  // this example is showing how we can initialize Embrace not using hooks  

  await initialize({  

    sdkConfig: {  

      ios: {appId: "__YOUR_APP_ID__"},  

    },  

  });  

  

  let embraceTracerProvider: TracerProvider;  

  try {  

    embraceTracerProvider = new EmbraceNativeTracerProvider();  

  } catch (e) {  

    console.log(  

      "Error creating `EmbraceNativeTracerProvider`. Will use global tracer provider instead",  

      e,  

    );  

  }  

  

  Navigation.registerComponent(  

    "HomeScreen",  

    () =>  

      (props) => {  

        // make sure to wrap the events registry instance in a React ref  

        const navRef = useRef(Navigation.events());  

  

        return (  

          <EmbraceNativeNavigationTracker  

            ref={navRef}  

            tracerProvider={embraceTracerProvider}  

            screenAttributes={{ // at the moment attributes can't be modified or included after an span is started  

              "test.attr": 98765,  

              dev: true,  

            }}>  

            <HomeScreen {...props} />  

          </EmbraceNativeNavigationTracker>  

        );  

      },  

    () => HomeScreen,  

  );  

  

  // rest of registration and configuration  

};  

  

// entry point of the app  

initApp();
```

--------------------------------

### Construct session URL

Source: https://embrace.io/docs/react-native/features/session-metadata

Template for building a direct URL to a specific session in the Embrace dashboard.

```text
https://dash.embrace.io/app/{app_id}/open?session_id={session_id}
```

--------------------------------

### Add Embrace Upload Symbols Map build phase

Source: https://embrace.io/docs/react-native/integration/upload-symbol-files

Execute the Embrace upload script in a new Xcode Run Script phase using the generated source map.

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

--------------------------------

### Configure Xcode Bundle React Native code and images phase

Source: https://embrace.io/docs/react-native/integration/upload-symbol-files

Modify the existing build phase to generate and export the source map file before the React Native bundle script runs.

```bash
set -e  

  

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"  

REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"  

  

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"
```

```bash
set -e  

  

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"  

  

# Add these two lines  

mkdir -p "$CONFIGURATION_BUILD_DIR/embrace-assets"  

export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/embrace-assets/main.jsbundle.map"  

  

REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"  

  

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"
```

--------------------------------

### Update Embrace symbol upload build phase

Source: https://embrace.io/docs/react-native/upgrading

Configure the build phase script to use the bundled upload script from the @embrace-io/react-native package.

```bash

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"  



```

--------------------------------

### Set JavaScript bundle path for OTA updates

Source: https://embrace.io/docs/react-native/integration/upload-symbol-files

Configure the SDK to locate the downloaded bundle on the device after an OTA update.

```javascript
import { setJavaScriptBundlePath } from '@embrace-io/react-native';  

  

setJavaScriptBundlePath(pathToBundle);
```

--------------------------------

### Apply Embrace Plugin in App build.gradle

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Apply the Embrace plugin in the application-level build.gradle file.

```gradle
apply plugin: 'com.android.application'  

apply plugin: 'io.embrace.gradle'  

repositories {  

  mavenCentral()  

  google()  

}  
```

--------------------------------

### Configure Metro for OTLP

Source: https://embrace.io/docs/react-native/features/otlp

Update metro.config.js to enable unstable_allowRequireContext for non-Expo projects.

```javascript
// metro.config.js  

module.exports = {  

  transformer: {  

    unstable_allowRequireContext: true,  

    // ... other configuration  

  },  

};
```

--------------------------------

### logMessage(message, severity, properties)

Source: https://embrace.io/docs/react-native/integration/log-message-api

Logs a message immediately to the Embrace backend.

```APIDOC
## logMessage(message, severity, properties)

### Description
Logs a message immediately to the Embrace backend. This is useful for troubleshooting difficult bugs or monitoring new version rollouts.

### Signature
`logMessage(message: string, severity: string, properties: object)`

### Parameters
- **message** (string) - Required - The log message content. Maximum length is 4000 characters.
- **severity** (string) - Required - The severity level of the log. Options include 'error', 'warning', and 'info'.
- **properties** (object) - Optional - A map of key-value pairs for categorization and filtering. Limited to 10 properties per log. Property keys are limited to 128 characters and values to 256 characters.

### Usage Example
```javascript
import { logMessage } from '@embrace-io/react-native';

logMessage('Loading not finished in time.', 'error', {
  propertyA: 'valueA',
  propertyB: 'valueB',
});
```
```

--------------------------------

### Configure Redux middleware without hooks

Source: https://embrace.io/docs/react-native/features/redux-actions

Sets up the Redux store with Embrace middleware using a standard initialization approach.

```typescript
import { configureStore, Tuple } from '@reduxjs/toolkit';  

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

import { EmbraceNativeTracerProvider } from '@embrace-io/react-native-tracer-provider';  

import { createEmbraceMiddleware } from '@embrace-io/react-native-redux';  

  

const setupStore = async () => {  

  await initialize({ sdkConfig: { ios: { appId: 'abc123' } } });  

  

  const tracerProvider = new EmbraceNativeTracerProvider();  

  

  return configureStore({  

    reducer: rootReducer,  

    middleware: () => new Tuple(createEmbraceMiddleware(tracerProvider)),  

  });  

};
```

--------------------------------

### Configure Android Desugaring

Source: https://embrace.io/docs/react-native/faq

Enable core library desugaring in the Android build configuration to support API levels below 26.

```gradle
android {  

   ...  

    compileOptions {  

        ...  

        coreLibraryDesugaringEnabled true  

    }  

}  

  

dependencies {  

    ...  

    coreLibraryDesugaring 'com.android.tools:desugar_jdk_libs:2.0.3' // 2.0.3 or higher  

}  
```

```properties
android.useFullClasspathForDexingTransform=true  
```

--------------------------------

### Log a message immediately

Source: https://embrace.io/docs/react-native/integration/log-message-api

Use the logMessage function to send a log event with a message, severity level, and optional properties.

```javascript
import { logMessage } from '@embrace-io/react-native';  

  

logMessage('Loading not finished in time.', 'error', {  

  propertyA: 'valueA',  

  propertyB: 'valueB',  

});
```

--------------------------------

### Log component visibility with breadcrumbs

Source: https://embrace.io/docs/react-native/features/components

Use addBreadcrumb for a lightweight way to record when a component is rendered without tracking duration.

```javascript
import { addBreadcrumb } from '@embrace-io/react-native';  

  

addBreadcrumb(`Rendered [${myComponent}]`);
```

--------------------------------

### Implement legacy navigation tracking with EmbraceNavigationTracker.build

Source: https://embrace.io/docs/react-native/features/navigation

Uses the older builder pattern to register navigation tracking for react-native-navigation.

```javascript
import { Navigation } from 'react-native-navigation';  

  

import EmbraceNavigationTracker from '@embrace-io/react-native-navigation';  

EmbraceNavigationTracker.build(Navigation);  

  

Navigation.registerComponent('myLaunchScreen', () => App);  

Navigation.events().registerAppLaunchedListener(() => {  

  Navigation.setRoot({  

    root: {  

      stack: {  

        children: [  

          {  

            component: {  

              name: 'myLaunchScreen',  

            },  

          },  

        ],  

      },  

    },  

  });  

});  
```

--------------------------------

### Implement modern navigation tracking with EmbraceNavigationTracker

Source: https://embrace.io/docs/react-native/features/navigation

Uses the updated component-based tracker with tracer provider integration for React Navigation.

```javascript
import React, {useRef} from "react";  

import {EmbraceNavigationTracker} from "@embrace-io/react-native-navigation";  

import {useEmbraceNativeTracerProvider} from "@embrace-io/react-native-tracer-provider";  

import {  

  NavigationContainer,  

  useNavigationContainerRef,  

} from "@react-navigation/native";  

  

function App() {  

  // Embrace initialization should happen before  

  

  // as of now if you inspect the source code of `useNavigationContainerRef` from `@react-navigation/native` you will see that it returns `navigation.current` instead of the entire shape of a reference  

  const navigationRefVal = useNavigationContainerRef();  

  // We need here the entire shape, so we re-create it and pass it down into the `ref` prop for the `EmbraceNavigationTracker` component.  

  const navigationRef = useRef(navigationRefVal)  

  

  const {tracerProvider} = useEmbraceNativeTracerProvider();  

  

  return (  

    // `NavigationContainer` is waiting for what `useNavigationContainerRef` is returning (both exported from `@react-navigation/native`)  

    <NavigationContainer ref={navigationRefVal}>  

      <EmbraceNavigationTracker  

        ref={navigationRef}  

        tracerProvider={tracerProvider}  

        screenAttributes={{  

        "static.attribute": 123456,  

        "custom.key": "abcd...",  

      }}>  

        <Screens... />  

      </EmbraceNavigationTracker>  

    </NavigationContainer>  

  );  

}  
```

--------------------------------

### Configure Redux middleware with hooks

Source: https://embrace.io/docs/react-native/features/redux-actions

Integrates Embrace middleware into a Redux store using React hooks for initialization.

```typescript
import React, {useEffect, useState} from "react";  

import {EnhancedStore, configureStore, Tuple} from "@reduxjs/toolkit";  

import {useEmbrace} from "@embrace-io/react-native";  

import {useEmbraceNativeTracerProvider} from "@embrace-io/react-native-tracer-provider";  

import {useEmbraceMiddleware} from "@embrace-io/react-native-redux";  

  

const MyApp = () => {  

  const {isStarted} = useEmbrace({ios: {appId: "__APP_ID__"}});  

  const {tracerProvider} = useEmbraceNativeTracerProvider({}, isStarted);  

  const {middleware} = useEmbraceMiddleware(tracerProvider);  

  const [store, setStore] = useState<EnhancedStore>();  

  

  useEffect(() => {  

    if (middleware && !store) {  

      setStore(  

        configureStore({  

          reducer: rootReducer,  

          middleware: () => new Tuple(middleware),  

        }),  

      );  

    }  

  }, [middleware, store]);  

  

  ...  

  

};
```

--------------------------------

### Add Session Property

Source: https://embrace.io/docs/react-native/features/identify-users

Annotate a session with device or session-specific metadata. Note the 128-character limit for keys and 256-character limit for values.

```javascript
import { addSessionProperty } from '@embrace-io/react-native';  

  

addSessionProperty('launch type', 'normal', false);
```

--------------------------------

### Configure disabled URL patterns in JavaScript

Source: https://embrace.io/docs/react-native/features/otlp

Add the disabledUrlPatterns key to the SDK_CONFIG object during initialization in the JS layer.

```json
"disabledUrlPatterns": [  

    "grafana.net"  

]
```

--------------------------------

### Enable network span forwarding on Android

Source: https://embrace.io/docs/react-native/features/network-spans-forwarding

Add the enable_network_span_forwarding attribute to the embrace-config.json file in the Android project.

```json
{

  "app_id": "xxxxx",

  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "sdk_config": {

    "app_framework": "react_native",

    "networking": {

      "enable_network_span_forwarding": true

    }

  }

}
```

--------------------------------

### Implement modern navigation tracking with EmbraceNativeNavigationTracker

Source: https://embrace.io/docs/react-native/features/navigation

Wraps the root view with the modern tracker component and configures the tracer provider for react-native-navigation.

```javascript
import { Navigation } from 'react-native-navigation';  

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

import { EmbraceNativeTracerProvider } from '@embrace-io/react-native-tracer-provider';  

import { TracerProvider } from '@opentelemetry/api';  

  

await initialize({  

  sdkConfig: {  

    ios: {  

      appId: '__APP_ID__',  

    },  

  },  

});  

  

let provider;  

try {  

  provider = new EmbraceNativeTracerProvider();  

} catch (e) {  

  console.log(  

    'Error creating `EmbraceNativeTracerProvider`. Will use global tracer provider instead',  

    e,  

  );  

}  

  

// entry point of app  

Navigation.registerComponent(  

  'HomeScreen',  

  (props) => () => {  

    const ref = useRef(Navigation.events());  

  

    return (  

      <EmbraceNativeNavigationTracker  

        ref={ref}  

        tracerProvider={provider}  

        screenAttributes={{  

          'test.attr': 98765,  

        }}>  

        <RootScreen {...props} />  

      </EmbraceNativeNavigationTracker>  

    );  

  },  

  () => RootScreen,  

);  

  

// rest of navigation + configuration  
```

--------------------------------

### Update Android embrace-config.json

Source: https://embrace.io/docs/react-native/upgrading

Add the app_framework field to your Android configuration file to specify react_native.

```json
{

  "app_id": "xxxxx",

  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "sdk_config": {

    "app_framework": "react_native"

  }

}
```

--------------------------------

### Update iOS Cocoapods

Source: https://embrace.io/docs/react-native/upgrading

Run this command in the ios directory to update dependencies after upgrading packages.

```bash
cd ios && pod install --repo-update
```

--------------------------------

### Pin OpenTelemetry dependencies in build.gradle

Source: https://embrace.io/docs/react-native/changelog

Use this resolution strategy to resolve okhttp version conflicts caused by transitive OpenTelemetry dependencies in Android SDK version 7.9.2.

```groovy
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")  

      }  

  }
```

--------------------------------

### Manage Span Lifecycle

Source: https://embrace.io/docs/react-native/features/traces

Create and end spans to track asynchronous operations.

```javascript
const span = tracer.startSpan('span-name');  

  

someAsyncOperation().then(() => span.end());
```

--------------------------------

### Remove Legacy Native Initialization

Source: https://embrace.io/docs/react-native/upgrading

Remove existing Embrace initialization calls from native AppDelegate files.

```objective-c
[[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkReactNative];
```

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

--------------------------------

### Configure disabled URL patterns in Android

Source: https://embrace.io/docs/react-native/features/otlp

Add the disabled_url_patterns key to the embrace-config.json file to ignore specific network request patterns.

```json
{

  "app_id": "xxxxx",

  "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",

  "sdk_config": {

    "app_framework": "react_native",

    "networking": {

      "enable_network_span_forwarding": true,

      "disabled_url_patterns": ["grafana.net"]

    }

  }

}
```

--------------------------------

### Configure Metro to Preserve Names

Source: https://embrace.io/docs/react-native/features/render-errors

Update metro.config.js to prevent minification from stripping class and function names, which helps in identifying components in error logs.

```javascript

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');  

  

const config = {  

  transformer: {  

    minifierConfig: {  

      keep_classnames: true,  

      keep_fnames: true,  

      mangle: {  

        keep_classnames: true,  

        keep_fnames: true,  

      },  

    },  

  },  

};  

  

module.exports = mergeConfig(getDefaultConfig(__dirname), config);  



```

--------------------------------

### Define Parent-Child Relationships

Source: https://embrace.io/docs/react-native/features/traces

Use the asParent helper to nest spans.

```javascript
import { asParent } from '@embrace-io/react-native-tracer-provider';  

  

const parentSpan = tracer.startSpan('the-parent');  

const childSpan = tracer.startSpan('the-child', {}, asParent(parentSpan));  

  

childSpan.end();  

parentSpan.end();
```

--------------------------------

### Update Bundle React Native Code Build Phase

Source: https://embrace.io/docs/react-native/integration/upload-symbol-files?platform=ios

Modify the existing Xcode build phase to generate and export the JavaScript source map file.

```bash
set -e  

  

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"  

REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"  

  

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"  
```

```bash
set -e  

  

WITH_ENVIRONMENT="$REACT_NATIVE_PATH/scripts/xcode/with-environment.sh"  

  

# Add these two lines  

mkdir -p "$CONFIGURATION_BUILD_DIR/embrace-assets"  

export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/embrace-assets/main.jsbundle.map"  

  

REACT_NATIVE_XCODE="$REACT_NATIVE_PATH/scripts/react-native-xcode.sh"  

  

/bin/sh -c "$WITH_ENVIRONMENT $REACT_NATIVE_XCODE"  
```

--------------------------------

### Retrieve last run end state

Source: https://embrace.io/docs/react-native/features/session-metadata

Determine if the previous app instance ended in a crash. Returns 'INVALID' if called before SDK initialization.

```javascript
import { getLastRunEndState } from '@embrace-io/react-native';  

  

getLastRunEndState().then((resp) => {  

  console.log('LastRunEndState', resp);  

});
```

--------------------------------

### Update Root build.gradle Classpath

Source: https://embrace.io/docs/react-native/upgrading

Manually update the buildscript classpath in the root android/build.gradle file to use the new embrace-gradle-plugin.

```gradle
// 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']}"
```

--------------------------------

### recordCompletedSpan(tracer, name, options)

Source: https://embrace.io/docs/react-native/features/traces

Records a span that has already completed.

```APIDOC
## recordCompletedSpan(tracer, name, options)

### Description
Convenience function to start and stop a span in a single call for operations that have already finished.

### Parameters
- **tracer** (object) - Required - The tracer instance.
- **name** (string) - Required - The name of the span.
- **options** (object) - Required - Configuration including `startTime`, `endTime`, `attributes`, `events`, and `parent`.
```

--------------------------------

### Update React Native Gradle Plugin

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Replace the legacy react.gradle application method with the modern facebook.react plugin.

```gradle
apply plugin: "com.facebook.react"  
```

--------------------------------

### Configure Span Attributes

Source: https://embrace.io/docs/react-native/features/traces

Add metadata to spans during creation or update them dynamically.

```javascript
// Add an attribute on create  

const span = tracer.startSpan('span-name', {  

  attributes: {  

    'my-attr-on-create': 'hello',  

  },  

});  

  

// Add an attribute later on  

span.setAttribute('my-other-attr', 'bye');
```

--------------------------------

### Enable unhandled promise rejection tracking

Source: https://embrace.io/docs/react-native/features/unhandled-promise-rejections

Use the trackUnhandledRejections flag within the useEmbrace hook to enable automatic error logging for unhandled promises.

```javascript
const { isStarted } = useEmbrace({  

  ios: { appId: '__APP_ID__' },  

  trackUnhandledRejections: true,  

});
```

--------------------------------

### Set User Identifier

Source: https://embrace.io/docs/react-native/features/identify-users

Annotate a session with a unique user identifier for later searching.

```javascript
import { setUserIdentifier } from '@embrace-io/react-native';  

  

setUserIdentifier('internal_random_id_1234');
```

--------------------------------

### Fix Expo ModulesProvider Build Error

Source: https://embrace.io/docs/react-native/integration/add-embrace-sdk

Import the ExpoModulesCore header in AppDelegate to resolve missing interface declarations.

```objective-c
#import "ExpoModulesCore-Swift.h"  
```

--------------------------------

### Add User Persona

Source: https://embrace.io/docs/react-native/features/identify-users

Annotate a session with a specific user persona to segment users based on behavior or attributes.

```javascript
import { addUserPersona } from '@embrace-io/react-native';  

  

addUserPersona('high_value_cart');
```

--------------------------------

### Mark Span as Failed

Source: https://embrace.io/docs/react-native/features/traces

Use the endAsFailed utility to terminate a span that encountered an error.

```javascript
import { endAsFailed } from '@embrace-io/react-native-tracer-provider';  

  

endAsFailed(span);
```

--------------------------------

### Retrieve current session ID

Source: https://embrace.io/docs/react-native/features/session-metadata

Obtain the current Embrace Session ID to link sessions with other observability tools. Must be called after SDK initialization to avoid returning null.

```javascript
import { getCurrentSessionId } from '@embrace-io/react-native';  

  

getCurrentSessionId().then((sessionId) => {  

  console.log('Embrace Session Id', sessionId);  

});
```

--------------------------------

### endAsFailed(span)

Source: https://embrace.io/docs/react-native/features/traces

Marks a span as failed.

```APIDOC
## endAsFailed(span)

### Description
Utility function to mark a span as failed.

### Parameters
- **span** (object) - Required - The span instance to mark as failed.
```

--------------------------------

### Retrieve device ID

Source: https://embrace.io/docs/react-native/features/session-metadata

Obtain the unique identifier for the current device.

```javascript
import { getDeviceId } from '@embrace-io/react-native';  

  

getDeviceId().then((deviceId) => {  

  console.log('Embrace Device Id', deviceId);  

});
```
Tokens:
Raw