diff --git a/docs/react-native/4x/features/current-device-id-api.md b/docs/react-native/4x/features/current-device-id-api.md new file mode 100644 index 00000000..edfdd6ea --- /dev/null +++ b/docs/react-native/4x/features/current-device-id-api.md @@ -0,0 +1,32 @@ +--- +title: Current Device ID API +sidebar_position: 9 +description: Get the Device ID. +--- +# Current Device ID API + +import GetSessionId from '@site/shared/get-session-id.md'; + + + +## Integration Steps + +In order to use this feature, you will need to follow two steps: + +1. Make sure your app is using at least version `4.0.0` of the Embrace SDK. +2. Implement the API call to obtain the current Device ID. + + +```javascript +import {getDeviceId} from '@embrace-io/react-native'; + +const myMethod = () =>{ + getDeviceId().then(deviceId=>{ + console.log("Embrace Device Id", deviceId) + }) +} +``` + +import CallSupport from '@site/shared/call-support.md'; + + \ No newline at end of file diff --git a/docs/react-native/4x/features/current-session-id-api.md b/docs/react-native/4x/features/current-session-id-api.md new file mode 100644 index 00000000..82f1b0f3 --- /dev/null +++ b/docs/react-native/4x/features/current-session-id-api.md @@ -0,0 +1,37 @@ +--- +title: Current Session ID API +sidebar_position: 9 +description: Track the current Embrace session by getting its ID. +--- +# Current Session ID API + +import GetSessionId from '@site/shared/get-session-id.md'; + + + +## Integration Steps + +In order to use this feature, you will need to follow two steps: + +1. Make sure your app is using at least version `3.15.0` of the Embrace SDK. +2. Implement the API call to obtain the current Session ID. +3. The method will return a String with the SessionId or null if there is no active session. + + +```javascript +import {getCurrentSessionId} from '@embrace-io/react-native'; + +const myMethod = () =>{ + getCurrentSessionId().then(sessionId=>{ + console.log("Embrace Session Id", sessionId) + }) +} +``` + +:::warning Important +If you call `getCurrentSessionId()` inside the `AppState change` listener; keep in mind that this is the moment when the session is ending, and a new one is starting. Therefore, there is a high chance that you will get the session ID of the session that is still ending. You might need to delay the call or obtain the session ID at any other point of the app lifecycle to make sure the session ID you get is the one you are looking for. +::: + +import CallSupport from '@site/shared/call-support.md'; + + \ No newline at end of file diff --git a/docs/react-native/4x/features/identify-users.md b/docs/react-native/4x/features/identify-users.md new file mode 100644 index 00000000..179a35c0 --- /dev/null +++ b/docs/react-native/4x/features/identify-users.md @@ -0,0 +1,66 @@ +--- +title: Identify Users +description: Get to know the users of your React Native application with the Embrace SDK +sidebar_position: 2 +--- + +# Know Your Users + +Embrace offers two ways you can annotate sessions with information that will help developers and customer service agents find +sessions for an unhappy user. + +1. [**User Personas**](/react-native/4x/features/identify-users#user-personas). This is data you can set and update about the user of a session. +1. [**Session Properties**](/react-native/4x/features/identify-users#session-properties). This is data you use to track information about the device or the session itself. + +## User Personas + +Embrace offers a set of methods to pass information about your users. + +```javascript +import {setUserIdentifier} from '@embrace-io/react-native'; + +setUserIdentifier('internal_random_id_1234'); +``` + +The above call annotates the session with a user identifier that you can use later to search for this user. +For more methods on setting user values, you can see the [source code](/api/react-native/). + +:::warning Important +Remember that this data will be uploaded to Embrace, so think about the privacy of your users and only include data you are willing to share. +We recommend using an anonymized or hashed user ID that only your agents can search for. +::: + +You can also set customized values for specific use cases or segments of users. + +```javascript +import {addUserPersona} from '@embrace-io/react-native'; + +addUserPersona('high_value_cart'); +``` + +In the above example, the session is annotated with `"high_value_cart"`. +This will help you identify users who have a certain dollar value in their shopping cart so you can prioritize fixing bugs that affect such users. + +## Session Properties + +Session Properties are another way to annotate the session. +The difference between session properties and [user personas](/react-native/4x/features/identify-users#user-personas) is that the former are for items relating to the session or the device and not necessarily to the user. +However, you are free to use both mechanisms interchangeably. + +Here is an example of setting a session property: + +```javascript +import {addSessionProperty} from '@embrace-io/react-native'; + +addSessionProperty('launch type', 'normal', false); +``` + +import PropertyLimit from '@site/shared/property-limit.md'; + + + +In the above, the `'launch type'` property is set with a value of `'normal'`. +This is to indicate normal launches by the user. +When the app is launched via a push notification tap, you can set the value `"push"`. +This can help to understand issues that are hurting push notification adoption rates. +For example, you could prioritize fixing the issues that affect customers that use push notifications, since they generally provide higher lifetime value. diff --git a/docs/react-native/4x/features/index.md b/docs/react-native/4x/features/index.md new file mode 100644 index 00000000..c15a8dc0 --- /dev/null +++ b/docs/react-native/4x/features/index.md @@ -0,0 +1,14 @@ +--- +title: Feature Reference +description: Learn about the advanced ways Embrace can help your application +sidebar_position: 2 +--- + +# React Native Feature Reference + +Embrace's SDK includes many advanced features that you can enable to help you understand more about +how your application is performing in production. + +1. [**Know your users.**](/react-native/4x/features/identify-users/) Add your own custom identifiers to users and sessions to make sure you can aggregate and find sessions correctly. +2. [**Tracking Components.**](/react-native/4x/features/tracking-components/) Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK. +3. [**Current Session ID API.**](/react-native/4x/features/current-session-id-api.md) This API lets you know what the current Session Id is in case you need to track it separately. diff --git a/docs/react-native/4x/features/last-run-end-state.md b/docs/react-native/4x/features/last-run-end-state.md new file mode 100644 index 00000000..2fddfcef --- /dev/null +++ b/docs/react-native/4x/features/last-run-end-state.md @@ -0,0 +1,62 @@ +--- +title: Last Run End State +description: Understand if the previous app instance ended in a crash +sidebar_position: 10 +--- + +# Last Run End State API + +This API enables customers to automatically/programmatically understand if the previous app instance ended in a crash. Depending on your use case, having the ability to query an API to understand if the previous app instance ended in a crash will enable you to adjust the behavior or UI of your app after a crash has occurred. + +**What do we mean by previous app instance?** + +A cold launch, basically. If the app gets backgrounded/resumed so a new session starts, the value returned will not change. So: + +1. App crashes +2. App is relaunched +3. `getLastRunEndState` returns "crashed" +4. App is sent to background +5. App is resumed, starting a new session +6. `getLastRunEndState` still returns "crashed" +7. App exits cleanly +8. App is relaunched +9. `getLastRunEndState` returns "clean exit" + +## Integration Steps + +In order to use this feature, you will need to follow two steps: + +1. Make sure your app is using the latest version of the Embrace SDK or at least React Native SDK 3.15.0 +2. Implement the API call after starting the SDK to receive the state of the last run. + +```javascript + useEffect(() => { + getLastRunEndState().then(resp => { + + console.log('LastRunEndState', resp); + }); + + }, []); +``` + +**Important Notes** + +:::warning Important +- The API can only be called after the SDK has been started. If a call is made prior to starting the Embrace SDK you will get a response of `INVALID` +- It will return that a crash occurred if the app crashed any time since the app last came to the foreground. This includes if the app crashed while running in the background. +::: + +### Version + +This feature is included in Embrace SDK version 3.15.0 and above. + +### Possible Values + +```typescript +/// Used to represent the end state of the last run of the application. +export type SessionStatus = 'INVALID' | 'CRASH' | 'CLEAN_EXIT'; +``` + +import CallSupport from '@site/shared/call-support.md'; + + diff --git a/docs/react-native/4x/features/tracing.md b/docs/react-native/4x/features/tracing.md new file mode 100644 index 00000000..f4ca7d13 --- /dev/null +++ b/docs/react-native/4x/features/tracing.md @@ -0,0 +1,299 @@ +--- +title: Performance Tracing (Beta) +description: Record traces to monitor the production performance and success rates of operations within your mobile app. +sidebar_position: 14 +--- + +# Performance Tracing (Beta) + +## Overview + +Embrace’s Performance Tracing solution gives you visibility into any app operation you’d like to track, including duration, success rate, and any contextual metadata collected at runtime that helps debug the root cause of your mobile app's performance issues. With our tool, you can quickly spot any bottlenecks in your app’s architecture, pinpoint areas you need to troubleshoot with high precision, and ultimately deliver a truly optimized user experience. + +## Feature Support + +:::info Minimum Requirements +- **We recommend using the latest Embrace React Native SDK version for the most up-to-date API**. Even though Performance Tracing is enabled in [Embrace React Native versions 4.1.0 and above](/react-native/4x/integration/add-embrace-sdk/). +::: + +The Embrace Performance Tracing API allows you to: + +- Create record data for past operations. + - To record past operations, you can specify the start and end times of your spans that you might have captured already. +- Add child spans to a parent span to track sub-operations within an operation. +- Attach attributes and span events to each span to give them further context + - Attributes allow you to specify string key-value pairs that can be useful for filtering, grouping, and deriving custom metrics + - Span events represent a point in time of the execution of the span and they can also have attributes + +There are no limits on the duration of a span as long as the app is running. + +There are also no limits to the number of child spans you can have per trace, provided the total number of spans do not exceed the per-session maximum. + +### Limits + +| Type | Limit | +| --- | --- | +| Max number of spans per session | 500 | +| Max number of attributes per span | 50 | +| Max number of events per span | 10 | +| Max number of attributes per event | 10 | +| Length of attribute keys | 50 characters | +| Length of attribute values | 200 characters | +| Length of Span names | 50 characters | +| Length of Event names | 100 characters | + +:::warning Exceeding Limits +If you exceed the listed limits, the operation with the limit-exceeding call will fail. See the API documentation for details. +::: + +### Naming Conventions + +- Span Names are **case-sensitive** and are a **max of 50 characters.** +- Key Names are **case-sensitive**, have a **max of 50 characters**, and are **alphanumeric ASCII characters** + +:::warning Internal Prefixes +The `emb-` and `emb.` prefixes are reserved for internal Embrace span and attribute names, respectively. You should never create a span or attribute key name with `emb-` and `emb.` prefixes +::: + +## Adding Performance Traces To Your App + +To use this feature: + +1. **Ensure you're using Embrace React Native version 4.1.0 or greater**. +3. Instrument your app using the reference guide in this section to start adding traces to your operations. +4. See the traces in the Traces section of the Embrace dashboard. + +### Install the component + +```shell-session +yarn add @embrace-io/react-native-spans +``` + +```shell-session +npm install @embrace-io/react-native-spans +``` + +## API Usage Examples + +### Create a Span + +```javascript +// create a trace by creating its root span +// recording will not behind until the span has been started + +import { startSpan } from '@embrace-io/react-native-spans'; + +// startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise; + +const spanId = await startSpan("parentname") + +``` + +### Create a Span that started in the past (or future) + +```javascript +// create a trace by creating its root span + +import { startSpan } from '@embrace-io/react-native-spans'; + +// startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise; +const startTimeMs = new Date().getTime() +const spanId = await startSpan("parentname", undefined, startTimeMs) + +``` + +### Add an Attribute to a Span + +```javascript +// add an attribute to a specific span + +import { startSpan, stopSpan, addSpanAttributeToSpan } from '@embrace-io/react-native-spans'; + +// addSpanAttributeToSpan: (spanId: string, key: string, value: string) => Promise; +// Starting a span +const spanId = await startSpan("parentname") + +// Adding an attribute to a specific span +addSpanAttributeToSpan(spanId, "myKey", "value") + +stopSpan(spanId) + +``` + +### Add an Event to a Span + +```javascript +// add an event to a specific span + +import { startSpan, stopSpan, addSpanEventToSpan } from '@embrace-io/react-native-spans'; + +// addSpanEventToSpan: (spanId: string, name: string, timeStampMs: number, +// attributes?: Attributes) => Promise; + +// Starting a span +const spanId = await startSpan("parentname") + +// Adding an event to a specific span + +const attributes = { + "key1":"value1", + "key2":"value2", + "key3":"value3", +} +addSpanEventToSpan(spanId, "eventName", new Date().getTime(), attributes) + +stopSpan(spanId) + +``` + +### Stop Span For Operation That Ended Earlier + + +```javascript +// Stopping a specific span + +import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; + +// stopSpan: (spanId: string, errorCode?: SPAN_ERROR_CODES, endTimeMs?:number) => Promise; +// type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown'; + +// Starting a span +const spanId = await startSpan("parentname") + +// Do something + +const endTimeMs = new Date().getTime() +// Stopping the span +stopSpan(spanId, "Failure", endTimeMs) + +``` + +### Stop Span For an Operation That Failed + +```javascript +// Stopping a specific span + +import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; + +// stopSpan: (spanId: string, errorCode?: SPAN_ERROR_CODES, endTimeMs?:number) => Promise; +// type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown'; + +// Starting a span +const spanId = await startSpan("parentname") + +try{ + // Do something that throw an error +}catch(e){ + // Stopping the span with an Error Code + stopSpan(spanId, "Failure") +} + +``` + +### Add a Child Span If the Parent Started Properly + + +```javascript +import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; + +// Starting Spans +const parentSpanId = startSpan("parentname") + +const firstChildSpanId = startSpan("firstchildname", parentSpanId) + +const secondChildSpanId = startSpan("secondchildname", firstChildSpanId) + +// Stopping Spans +stopSpan(firstChildSpanId) +stopSpan(secondChildSpanId) +stopSpan(parentSpanId) + +``` + +:::info Minimum Requirements +- In order for a child span to be recorded, you must stop it before stopping the parent span. +::: + +### Create a span around a function (It will stop after the function finish) + +```javascript +// This method will start a span, add attributes / events (optional) to it, execute the function and stop to the span + +import { recordSpan } from '@embrace-io/react-native-spans'; + +// recordSpan: (name: string, callback: () => void | Promise, attributes?: Attributes, +// events?: Events[], parentSpanId?: string) => Promise; +// interface Attributes { +// [key: string]: string; +// } +// interface Events { +// name: string; +// timeStampMs?: number; +// attributes?: Attributes; +// } + +const trackMe = async ()=>{ + +} +const attributes = { + "key1":"value1", + "key2":"value2", + "key3":"value3", +} + const events = [ + { + name: 'eventName', + timeStampMs: new Date().getTime(), + attributes: {"eventKey": 'value'}, + }, +]; +// Starting Spans +const spanResult = await recordSpan("parentname", trackMe, attributes, events) + +``` + +### Create a span around a function (It will stop after the function finish) + +```javascript +// This method will create a span, add attributes / events (optional) to it, for a specific time + +import { recordCompletedSpan } from '@embrace-io/react-native-spans'; + +// recordCompletedSpan: (name: string, startTimeMS: number, endTimeMS: number, +// errorCode?: SPAN_ERROR_CODES, parentSpanId?: string, attributes?: Attributes, +// events?: Events[]) => Promise; + +// type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown'; +// interface Attributes { +// [key: string]: string; +// } +// interface Events { +// name: string; +// timeStampMs?: number; +// attributes?: Attributes; +// } + +const attributes = { + "key1":"value1", + "key2":"value2", + "key3":"value3", +} + const events = [ + { + name: 'eventName', + timeStampMs: new Date().getTime(), + attributes: {"eventKey": 'value'}, + }, +]; + +const startTime = new Date().getTime() +const endTime = new Date().getTime() + 1 + +const spanResult = await recordCompletedSpan: ("parentname", startTime, + endTime, "None", undefined, attributes, events) + +``` + +## Support + +If you have any questions or if something is not working as intended, please get in touch with your Customer Success Manager. \ No newline at end of file diff --git a/docs/react-native/4x/features/tracking-components.md b/docs/react-native/4x/features/tracking-components.md new file mode 100644 index 00000000..24c19ad1 --- /dev/null +++ b/docs/react-native/4x/features/tracking-components.md @@ -0,0 +1,32 @@ +--- +title: Tracking Components +description: Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK +sidebar_position: 3 +--- + +# Tracking Components + +By default, Embrace will track native views. +If you'd like to track when a React component is mounted and unmounted, you can do so with the `startView` and `endView` functions. + +These methods are flexible, so it's up to you as a developer to define when a view "starts" and "ends". +Perhaps it's when a component is mounted and unmounted, or maybe it's when a style is applied that makes the component visible or not visible to the user. + +```javascript +import {startView, endView} from '@embrace-io/react-native'; + +startView('MyView'); + +endView('MyView'); +``` + +There's also a `logScreen` function available, which will log a breadcrumb with the name of the component. +This could be helpful as a lightweight option to breadcrumb which components were visible if you don't care about the duration the component was visible for. +In most cases it's recommended to use `startView` and `endView`. + +```javascript +import {logScreen} from '@embrace-io/react-native'; + +// This will add a breadcrumb to the session with the following format: "Opening screen [MyView]". +logScreen('MyComponent'); +``` diff --git a/docs/react-native/4x/index.md b/docs/react-native/4x/index.md new file mode 100644 index 00000000..34b93d52 --- /dev/null +++ b/docs/react-native/4x/index.md @@ -0,0 +1,29 @@ +--- +title: 4.x SDK +sidebar_position: 6 +description: Using the Embrace React Native 4.x SDK +--- + +# React Native Platform Documentation + +:::warning + +This version of the Embrace React Native SDK is deprecated. Please consider [upgrading](/react-native/upgrading/) to +the latest. + +::: + +## Getting Started + +This documentation is split into two sections: + +1. [**Integration Guide**](/react-native/4x/integration/) +2. [**Feature Reference**](/react-native/4x/features/) + +If you are just starting out with Embrace, follow the [**Integration Guide**](/react-native/4x/integration/) to learn +the key steps to successfully using our product. + +Once you've completed that, browse through our [**Feature Reference**](/react-native/4x/features/) guides to learn how +to use the advanced features our SDK provides. + +You can also view our [Changelog](/react-native/changelog/) diff --git a/docs/react-native/4x/integration/add-embrace-sdk.md b/docs/react-native/4x/integration/add-embrace-sdk.md new file mode 100644 index 00000000..99bb672b --- /dev/null +++ b/docs/react-native/4x/integration/add-embrace-sdk.md @@ -0,0 +1,201 @@ +--- +title: Adding the Embrace SDK +description: Add the Embrace SDK as a dependency to your React Native application +sidebar_position: 3 +--- + +# Adding the React Native Embrace SDK + +## Add the JavaScript library + +Use Yarn or NPM to install the NPM module. + +```shell-session +yarn add @embrace-io/react-native +``` + +```shell-session +npm install @embrace-io/react-native --save +``` + +:::info +If you are using a yarn workspace, you must run the command at the react-native application folder level or modify package.json manually. Do not run this on your yarn workspace root. +::: + +# Adding the SDK + +## 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/dist/scripts/setup` + +**Run the setup script** +```shell-session +node node_modules/@embrace-io/react-native/lib/scripts/setup/installAndroid.js +``` + +```shell-session +node node_modules/@embrace-io/react-native/lib/scripts/setup/installIos.js +``` + +:::info 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 +```shell-session +node node_modules/@embrace-io/react-native/lib/scripts/setup/uninstall.js +``` +::: + +You can use git to see the changes that the script made. + +```shell-session +git diff +``` + +Compare the changes to the [Manual Setup](/android/integration/add-embrace-sdk#adding-the-sdk-manually) step to verify the changes were made +correctly. + +## Manually + + + + +You'll need to add an `Embrace-Info.plist` file at the root of the iOS project. + +1. Create a file called `Embrace-Info.plist` with the following content. +```xml + + + + + API_KEY + {API_KEY} + CRASH_REPORT_ENABLED + + + +``` +:::info Note for iOS +If you'd like to use Embrace's internal crash reporter, +set the `CRASH_REPORT_ENABLED` field to true in the `Embrace-Info.plist` file that you created earlier (as +described in the [Adding the Embrace SDK](/flutter/integration/add-embrace-sdk) page). +If you're using Crashlytics, set this value to false. +::: + +2. Identify your root iOS Project. + + +3. Right click on that project and select `Add Files to YOUR_PROJECT`. + + +4. Select `Embrace-Info.plist` and click on `Add`. Do not forget to select which `Targets` you are using. + + +5. Check if the file appears inside YOUR_PROJECT. + + +## React Native Version < 0.60 + +If you're on React Native version 0.60 and above, you can use [Autolinking](https://github.com/react-native-community/cli/blob/dec33cb945be548a0d30c2ea073493e253239850/docs/autolinking.md#platform-ios) +to set up the native modules. + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + + + + +Configure your `PodFile` to add Embrace. (RN Versions < 0.6) + +```ruby +target 'MyApp' do + # ... + + pod 'EmbraceIO' + pod 'RNEmbrace', :path => '../node_modules/@embrace-io/react-native' +end +``` +Then, install the pod. + +```shell-session +cd ios && pod install --repo-update +``` + + + + + + + +Update the `build.gradle` file (usually located at `/android/build.gradle`) to include the Embrace Swazzler. + +```groovy +buildscript { + repositories { + mavenCentral() + google() + } + dependencies { + classpath "io.embrace:embrace-swazzler:${findProject(':embrace-io_react-native').properties['emb_android_sdk']}" + } +} +``` + +Then, update the app `build.gradle` file (usually located at `/android/app/build.gradle`). + +```groovy +apply plugin: 'com.android.application' +apply plugin: 'embrace-swazzler' +repositories { + mavenCentral() + google() +} +``` + +:::warning Important +React Native 0.59.0 and later automatically adds the required `compileOptions` directive to the `android/app/build.gradle` file. +If you are using a version of React Native older than 0.59.0, or your project was created with a version older than 0.59.0, add the following to your `android/app/build.gradle` file: + +```groovy +android { + // ... + + compileOptions { + sourceCompatibility JavaVersion.VERSION_1_8 + targetCompatibility JavaVersion.VERSION_1_8 + } + // ... +} +``` + +::: + +Now, add the Embrace config file at `android/app/src/main/embrace-config.json`, and add your API key and token. + +```json +{ + "app_id": "xxxxx", + "api_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" +} +``` + +:::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. diff --git a/docs/react-native/4x/integration/breadcrumbs.md b/docs/react-native/4x/integration/breadcrumbs.md new file mode 100644 index 00000000..11ad1e06 --- /dev/null +++ b/docs/react-native/4x/integration/breadcrumbs.md @@ -0,0 +1,33 @@ +--- +title: Breadcrumb Logs +description: Add logging to your React Native application using Breadcrumbs with the Embrace SDK +sidebar_position: 7 +--- + +# Add a Breadcrumb + +## Adding Context to Sessions + +Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](/react-native/4x/integration/crash-reporting/) and [Session Reporting](/react-native/4x/integration/session-reporting/) sections. +Embrace can also collect your logging data and include it as context within your sessions. +Here's how you add a Breadcrumb to the session. + +```javascript +import {addBreadcrumb} from '@embrace-io/react-native'; + +addBreadcrumb("component updated -- 'show' prop changed from true to false"); +``` + +In the above example, a Breadcrumb is being logged when a prop named "show" changed and triggered a component update. +This event is not otherwise shown in the session and can be important depending on what the user does next. + +:::info +For how to best use Breadcrumbs, check out the [Best Practices](/best-practices/breadcrumbs/) page. +::: + +--- + +We generally use the Breadcrumb method for our logging and not the Log Message API to add context to sessions. +Breadcrumbs are a lightweight way to add logging to your session. They add no CPU or memory overhead, and trigger no networking calls. +The Log Message API is a much heavier mechanism. We will learn about it in the [Alerting](/react-native/4x/integration/log-message-api/) section of the documentation. +For now, just know that using Breadcrumbs is the right thing to do most of the time. diff --git a/docs/react-native/4x/integration/crash-reporting.md b/docs/react-native/4x/integration/crash-reporting.md new file mode 100644 index 00000000..aa144ffa --- /dev/null +++ b/docs/react-native/4x/integration/crash-reporting.md @@ -0,0 +1,107 @@ +--- +title: Crash Reporting +description: Upload crash reports for both native and JavaScript exceptions from your React Native application using the Embrace SDK +sidebar_position: 6 +--- + +# Collect your first crash report + +## Setting up the Crash Reporter + +If you've been following along, you should be setup to collect native crash reports. +To upload crash reports from unhandled JavaScript exceptions, add the following in the entrypoint of the React app. + +```javascript +import {initialize} from '@embrace-io/react-native' +// Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish + +initialize().then(hasStarted=>{ + if(hasStarted){ + //doSomething + } +}); +:::info Note for initialize method +The initialize method will apply the interceptors needed to get information from your app. Since its a Promise, so you might want to "await" or "then" it before doing something else. +::: + + +``` + +This will setup a hook that gets called and uploads a crash report when the application crashes because of an unhandled JavaScript exception. +You can also pass in a patch number to the `initialize` function to use along side the version of the app to pinpoint which JavaScript bundle the user was running when the app crashed. + +```javascript +// Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish + +initialize({patch: 'v1'}); +``` + +:::info Note for iOS +If you'd like to use Embrace's internal crash reporter, +set the `CRASH_REPORT_ENABLED` field to true in the `Embrace-Info.plist` file that you created earlier (as +described in the [Adding the Embrace SDK](/react-native/4x/integration/add-embrace-sdk) page). +If you're using Crashlytics, set this value to false. +::: + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + +:::warning OTA Updates +If you distribute updated JavaScript bundles outside of the App Store/Google +Play Store, you will +need to point the Embrace SDK to where the most up to date bundle is installed +on the device. Otherwise, the stack traces will not be translated properly. +If you use CodePush, this is done automatically and there is no need to point +the Embrace SDK to where CodePush downloads the latest JavaScript bundle. + + + + +```javascript +import {setJavaScriptBundlePath} from '@embrace-io/react-native'; + +setJavaScriptBundlePath('/path/to/bundle'); +``` + + + + +```objectivec +[[RNEmbrace sharedIntance] setJavasScriptBundleURL: pathToBundle]; +``` + + + + +```java +Embrace.getInstance().getReactNativeInternalInterface().setJavaScriptBundleUrl(pathToBundle); +``` + + + + +::: + +## Triggering a Crash + +Now we're ready to trigger a crash. +Either crash the app organically, or add the following code to make it crash. + +```javascript +throw new Error('This is a crash'); +``` + +Embrace only uploads crash reports for applications that are running in release mode. +Build and run your application in release mode. + +Remember that Embrace sessions only upload on subsequent launches. +This means that after seeing the application crash, you must now launch the application again for that crashed session to upload to the Embrace servers. + +Once uploaded you should notice that your session is marked with the "crashed" icon. +Additionally your crash is visible in the crashes section of the dashboard. + +--- + +In the next guide, you'll learn how to add context to your sessions using Breadcrumb Logs. diff --git a/docs/react-native/4x/integration/index.md b/docs/react-native/4x/integration/index.md new file mode 100644 index 00000000..d00c2cf4 --- /dev/null +++ b/docs/react-native/4x/integration/index.md @@ -0,0 +1,27 @@ +--- +title: Integration Guide +description: Get started with integrating Embrace into your React Native application +sidebar_position: 1 +--- + +# React Native Integration + +## Getting Started + +This guide will walk you through integrating Embrace into your React Native application with a series of articles. We recommend following them in order, although you are free to skip around. + +## Requirements + +### Android + +* Android: Android 7.0 (API 24) +* `minSdkVersion`: 24 or higher +* `compileSdkVersion`: 34 or higher +* Java 1.8 +* Kotlin 1.4 +* Gradle 7.5.1 +* AGP (Android Gradle Build Tools Plugin) 7.2.2 + +### Expo + +For Expo apps, the project must be ejected (use `expo eject` for older versions or `expo prebuild` for newer versions) to integrate the necessary native components. diff --git a/docs/react-native/4x/integration/integration-steps.md b/docs/react-native/4x/integration/integration-steps.md new file mode 100644 index 00000000..fbfc2bd2 --- /dev/null +++ b/docs/react-native/4x/integration/integration-steps.md @@ -0,0 +1,18 @@ +--- +title: Integration Steps +description: Integration steps to add Embrace to your React Native application +sidebar_position: 1 +--- + +# Integration Steps + +1. [**Login to the Embrace Dashboard.**](/react-native/4x/integration/login-embrace-dashboard) Your data is available in the dashboard. It is important that you have this open while working on the integration to monitor progress. +1. [**Adding the Embrace SDK.**](/react-native/4x/integration/add-embrace-sdk) We'll be adding the Embrace SDK to your project. +1. [**Upload Symbol Files**](/react-native/4x/integration/upload-symbol-files) Learn which files need to be uploaded to make sure stack traces are translated. +1. [**Create Your First Session.**](/react-native/4x/integration/session-reporting) You'll launch your app after you've + initialized Embrace, and be able to see your first session in the Embrace + Dashboard. +1. [**Collect Your First Crash Report.**](/react-native/4x/integration/crash-reporting) Generate a crash and see the report that + gets uploaded. +1. [**Add a Breadcrumb.**](/react-native/4x/integration/breadcrumbs) Log messages using the Embrace SDK. +1. [**Add Alerts.**](/react-native/4x/integration/log-message-api) Use Embrace's Log Events to power a real-time alerting system so you can rest easy knowing we will tell you if your application breaks. diff --git a/docs/react-native/4x/integration/log-message-api.md b/docs/react-native/4x/integration/log-message-api.md new file mode 100644 index 00000000..8c1b52a7 --- /dev/null +++ b/docs/react-native/4x/integration/log-message-api.md @@ -0,0 +1,57 @@ +--- +title: Log Message API +description: Trigger alerts for your React Native application using logs with the Embrace SDK +sidebar_position: 10 +--- + +# Adding Logs + +As we've discussed in the [Session Reporting section](/react-native/4x/integration/session-reporting), Embrace uploads its sessions on the next app launch. +This delay may seem like it hurts the immediacy of the data you are seeing, but the reality is that at scale this still means you are finding out about issues very quickly. + +However, some situations might require instant feedback, such as hunting an especially difficult bug, troubleshooting on behalf of high-value users, or monitoring a new version rollout. + +You can leverage the log message API for this. + +## Using the Log Message API + +You can log a message immediately by calling the `logMessage` function. + +```javascript +import {logMessage, ERROR} from '@embrace-io/react-native'; + +logMessage( + 'Loading not finished in time.', + ERROR, + {propertyA: 'valueA', propertyB: 'valueB'}, +); +``` + +Here's a breakdown of the arguments being passed to the `logMessage` function. + +1. **The message.** The string of the log message. Make this short yet informative. +1. **Severity.** Other options include `WARNING` and `INFO`. +1. **Properties.** A map of key-value pairs you can use to categorize and filter log messages with. + +import LogLimit from '@site/shared/log-limit.md'; + + + +## Being Alerted on Logs + +Once you start using our alerting feature you can also configure how these are handled on the backend. +Using the Embrace Dashboard, you can configure email alerts to be sent to your team when certain thresholds are met with log events. +For example, let's say you have a steady rate of 1% for a given log event. You could set that as a threshold and receive an email if the rate rises beyond that in a sustained way. + +## Best Practices + +Logging a message using the Log Message API makes a network request immediately. +Sending too many logs can easily impact application performance or battery life. + +:::info +For more tips on making the most of the Log Message API, checkout the [Best Practices](/best-practices/log-message-api). +::: + +--- + +Congratulations! By this point, you should have a solid integration. Continue to the [Next Steps](/react-native/4x/integration/next-steps) page to wrap up your integration. diff --git a/docs/react-native/4x/integration/login-embrace-dashboard.md b/docs/react-native/4x/integration/login-embrace-dashboard.md new file mode 100644 index 00000000..41ec6c8a --- /dev/null +++ b/docs/react-native/4x/integration/login-embrace-dashboard.md @@ -0,0 +1,35 @@ +--- +title: Login to the Embrace Dashboard +description: Login to the Embrace dashboard to get started with your React Native integration +sidebar_position: 2 +--- + +# Getting Started with the Embrace Dashboard + +## Logging In + +Before being able to integrate, you'll need to create an account on the Embrace +dashboard so you can access your app ID and API token. Open a browser and +navigate to [dash.embrace.io](https://dash.embrace.io/). + +Either login if you have created an account already, or follow the prompts to +register for a new one. + + + +## Integration page + +Once you've finished logging in or registering for a new account, you'll be able +to create a new app. Follow the prompts until you get to the integration page. +Keep this tab open in your browser throughout the integration process. This will +assist you in verifying that data is sent, along with helping you become +familiar with the features the Embrace Dashboard offers. + +:::info +Take note of the app ID and API token, as you'll need those when integrating the +Embrace SDK with your app. +::: + + + +Now we are ready to add the SDK to your app. diff --git a/docs/react-native/4x/integration/next-steps.md b/docs/react-native/4x/integration/next-steps.md new file mode 100644 index 00000000..4aca84ea --- /dev/null +++ b/docs/react-native/4x/integration/next-steps.md @@ -0,0 +1,30 @@ +--- +title: Next Steps +description: Resources to help you take your Embrace integration for your React Native application to the next level +sidebar_position: 11 +--- + +# Next Steps + +## Wrapping Up + +Congratulations on completing the React Native integration guide! + +If you found anything confusing or have suggestions on improving the docs, +please don't hesitate to reach out to us at [support@embrace.com](mailto:support@embrace.com) or on Slack. + +## Feature Reference + +Embrace includes many optional advanced features that can help you figure out some of +the most challenging issues. Learn about these features, and how to enable them, in +our [Feature Reference](/react-native/4x/features/). + +## API Docs + +To see the full list of methods that the Android Embrace SDK exposes, please see +the [source repository](/api/react-native/). + +## Best Practices + +We offer further guides in the [Best Practices](/best-practices/) section of the docs. +Be sure to check these out, as they'll help you make decisions that will allow you to make the most of Embrace. diff --git a/docs/react-native/4x/integration/session-reporting.md b/docs/react-native/4x/integration/session-reporting.md new file mode 100644 index 00000000..44a6e8ae --- /dev/null +++ b/docs/react-native/4x/integration/session-reporting.md @@ -0,0 +1,228 @@ +--- +title: Session Reporting +description: Upload session reports from your React Native application using the Embrace SDK +sidebar_position: 5 +--- + +# Session Reporting + +Now that you’ve added the Embrace SDK to your project and can login to the Embrace dashboard, you’re ready to create your first session. +Here are the steps you’ll be taking to create your first session. + +1. [Import Embrace](/react-native/4x/integration/session-reporting#import-embrace) +1. [Add a start call to the Embrace SDK](/react-native/4x/integration/session-reporting#add-the-start-call) +1. [End the Startup Moment](/react-native/4x/integration/session-reporting#end-the-startup-moment) +1. [Build and run the application](/react-native/4x/integration/session-reporting#build-and-run-the-application) +1. [Trigger a session upload](/react-native/4x/integration/session-reporting#trigger-a-session-upload) + +## Initialize Embrace SDK + +Initialize method applies the necessary listener to your application. This allows Embrace to track javascript errors, check js bundle changes (if you use OTA), track js patch and react native versions. + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + + + + +```javascript +import {initialize} from '@embrace-io/react-native'; + +export default class App extends Component { + componentDidMount() { + // Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish + + initialize().then(hasStarted=>{ + if(hasStarted){ + //doSomething + } + }); + } +} +``` + + + +```javascript +import React, {useEffect, useState} from 'react' +import {initialize} from '@embrace-io/react-native'; + +const App = ()=> { + + useEffect(()=>{ + // Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish + + initialize().then(hasStarted=>{ + if(hasStarted){ + //doSomething + } + }); + },[]) + + return ... +} +export default App +``` + + + + +:::info Note for initialize method +The initialize method will apply the interceptors that we need to get information from your app. Since its a Promise, so you might want to "await" or "then" it before doing something else. +::: +## Starting Embrace SDK from Android / iOS + +:::info +Initializing the Embrace SDK from React Native (Javascript) will initialize the native Embrace SDKs (Android / iOS). This means that the network, crash, and metrics interceptors will be initialized once JavaScript is loaded and has called initialize method mentioned in the previous step. This is useful only if you perform some function/have custom code before initializing the application. If you want to start applying the interceptors as soon as Android / iOS has started, you can proceed with the Native integration. + +::: + + +Start by importing the Embrace native SDK in the file that applies for each platform. + + + + + + +Open the `AppDelegate.m` file (usually located at `/ios//AppDelegate.m`) and import Embrace. +```objectivec +#import +``` + + + + +Open the `MainApplication.java` file (usually located at `/android/app/src/main/java/com//MainApplication.java`) and import Embrace. + +```java +import io.embrace.android.embracesdk.Embrace; +``` + + + + +:::info +If you used the setup script mentioned on the [Adding the Embrace SDK](/react-native/4x/integration/add-embrace-sdk) page, this change has already been made for you. +::: + +## Add the Start Call + +After importing Embrace, update the same files that you edited in the previous step to make a call to the Embrace SDK to start capturing data. + + + + +```objectivec +@implementation AppDelegate +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions +{ + // Replace with your APP_ID, which is a 5-character value, e.g. "aBc45" + [[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkReactNative]; + + return YES; +} +``` + +:::info +If you are using Swift, follow the steps in the [iOS Linking Embrace](/ios/5x/integration/session-reporting) section. +::: + + + + +```java +public class MainApplication extends Application implements ReactApplication { + + @Override + public void onCreate() { + super.onCreate(); + // Add this line right after the super.onCreate(); + Embrace.getInstance().start(this, false, Embrace.AppFramework.REACT_NATIVE); + } +} +``` + + + + +## End the Startup Moment + +Embrace automatically starts the **startup** moment when your application launches. +For now, you can think of the startup moment as a timer that measures how long it took your application to launch. +Although in both Android and iOS the moment is started automatically, ending it is platform specific. + +For Android, the SDK will end the moment automatically. +To end the startup moment when you React component mounts, see the [Android guide](/android/integration/session-reporting#end-the-startup-moment) to prevent the moment from ending automatically. + +The iOS SDK does not end the moment automatically. + +In either platform, you can end the startup moment when your application mounts. + + + + +```javascript +import {endAppStartup} from '@embrace-io/react-native'; + +export default class App extends Component { + componentDidMount() { + endAppStartup(); + } +} +``` + + + + +```javascript +import React, {useEffect, useState} from 'react' +import {endAppStartup} from '@embrace-io/react-native'; + +const App = ()=> { + + useEffect(()=>{ + endAppStartup(); + },[]) + + return ... +} +export default App +``` +:::info + +As useEffect does not block the render thread, unlike componentDidMount, it might be necessary to add a variable such as isReady to wait until all your background process are finished and the user is able to interact with the application. + +::: + + + + +End the startup moment as soon as your users are able to interact with the application. + +## Build and Run the Application + +Now you're ready to build and run the application. +Launch the application how you usually would during development. + +:::info +If you encounter any errors, please get in touch on Slack and we can assist you. +::: + +## Trigger a Session Upload + +To trigger a session upload, simply stop the application by either force killing +it or using the stop button in either Xcode for iOS or Android Studio for Android. +Now run the application again. +This second launch will upload the previous session immediately. +Refresh the dashboard in your browser and you should now see that you've moved on to the next step. + +--- + +Congratulations! At this point you've completed a basic integration of Embrace. +Embrace is already collecting interesting data from your application. You can +see this data by browsing around the timeline page for the session you just captured. + +Up next, you'll be learning about uploading crash reports. diff --git a/docs/react-native/4x/integration/track-navigation-screens.md b/docs/react-native/4x/integration/track-navigation-screens.md new file mode 100644 index 00000000..77e2f552 --- /dev/null +++ b/docs/react-native/4x/integration/track-navigation-screens.md @@ -0,0 +1,147 @@ +--- +title: Track Screens +description: Add logging to your React Native application to track screens using the Embrace SDK +sidebar_position: 8 +--- + +# Track React Native Screens + +## Adding Context to Sessions + +Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](/react-native/4x/integration/crash-reporting) and [Session Reporting](/react-native/4x/integration/session-reporting) sections. +Embrace can also collect the screens that your app opened and include it as context within your sessions. +Here's how you add the screen tracker to the session. + +## Add React Navigation screen tracker + +### Adding the component + +Embrace has a separate module for tracking Screens, to use it you will need to add the React Navigation Tracker + +#### Install the component + +```shell-session +yarn add @embrace-io/react-navigation +``` + +```shell-session +npm install @embrace-io/react-navigation +``` + +#### Adding the component to your code + +Add an useRef for the NavigationContainer and pass it to Embrace's hook + +```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 + + + + ); +} +``` + +## Add React Native Navigation screen tracker + +### Adding the component + +Embrace has a separate module for tracking Screens, to use it you will need to add the React Native Navigation Tracker + +#### Install the component + +```shell-session +yarn add @embrace-io/react-native-navigation +``` + +```shell-session +npm install @embrace-io/react-native-navigation +``` + +#### Adding the component to your code + +Apply the EmbraceNavigationTracker to your Navigation instance. You should do this in your entry point, usually index.js + +:::info +If you have more than one navigation instance, you can pass a second parameter to the build method with an identifier +::: + +```javascript +import {Navigation} from 'react-native-navigation'; + +// Start - Add those lines +import EmbraceNavigationTracker from '@embrace-io/react-native-navigation'; +EmbraceNavigationTracker.build(Navigation); +// End - Add those lines + +Navigation.registerComponent('myLaunchScreen', () => App); +Navigation.events().registerAppLaunchedListener(() => { + Navigation.setRoot({ + root: { + stack: { + children: [ + { + component: { + name: 'myLaunchScreen', + }, + }, + ], + }, + }, + }); +}); +``` + +:::info +Currently we are only supporting 'React Native Navigation SDK' and 'React Navigation SDK', if you are using another library please contact us at [support@embrace.com](mailto:support@embrace.com) or on Slack if you would like to request support. +::: + +### Disable Auto Tracking for Native Screens + +Embrace automatically collects the native screens, if you do not want to see them in the session you can disable it. + +#### Android: +Go to your embrace-config.json inside android/app/src/main and add the sdk_config, your file should be like this + +```javascript +{ + "app_id": "APP_ID", + "api_token": "API_TOKEN", + ... + // Add this lines + "sdk_config": { + "view_config": { + "enable_automatic_activity_capture": false + } + } +} +``` + +#### iOS: + +Go to your Embrace-info.plist inside ios/YOURAPPNAME and add ENABLE_AUTOMATIC_VIEW_CAPTURE as false, your file should be like this + +```xml + + + + + API_KEY + {API_KEY} + CRASH_REPORT_ENABLED + + + ENABLE_AUTOMATIC_VIEW_CAPTURE + + + +``` diff --git a/docs/react-native/4x/integration/track-redux-actions.md b/docs/react-native/4x/integration/track-redux-actions.md new file mode 100644 index 00000000..25a5643c --- /dev/null +++ b/docs/react-native/4x/integration/track-redux-actions.md @@ -0,0 +1,54 @@ +--- +title: Track Redux's Actions +description: Add logging to your React Native application to track actions dispatched using the Embrace SDK +sidebar_position: 9 +--- + +# Add React Actions tracker + +## Adding Context to Sessions + +Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](/react-native/4x/integration/crash-reporting) and [Session Reporting](/react-native/4x/integration/session-reporting) sections. +Embrace can also collect the redux's actions that are being dispatched and include it as context within your sessions. +Here's how you add the action tracker to the session. + +:::info +Currently we are only supporting the Redux SDK and others libraries that supports middleware as Saga, if you are using another library please contact us at [support@embrace.com](mailto:support@embrace.com) or on Slack if you would like to request support. +::: + +## Adding the component + +Embrace has a separate module for tracking Redux's Actions, to use it you will need to add the Action Tracker + +### Install the component + +```shell-session +yarn add @embrace-io/react-native-action-tracker +``` + +```shell-session +npm install @embrace-io/react-native-action-tracker +``` + +### Adding the component to your code + +Add the Embrace's Middleware to your middleware's list + +```javascript +import {applyMiddleware, compose, configureStore} from '@reduxjs/toolkit'; +import {buildEmbraceMiddleware} from '@embrace-io/react-native-action-tracker'; +import myReducer from './reducers/MyReducer'; +import otherMiddleware from './middlewares/OtherMiddleware'; + +//Add the embrace middleware 'buildEmbraceMiddleware' an +const middlewareEnhancer = applyMiddleware(otherMiddleware(), buildEmbraceMiddleware()); + +const composedEnhancers = compose(middlewareEnhancer); + +export default configureStore({ + reducer: { + myReducer: myReducer, + }, + enhancers: [composedEnhancers], +}); +``` diff --git a/docs/react-native/4x/integration/track-screen-orientation.md b/docs/react-native/4x/integration/track-screen-orientation.md new file mode 100644 index 00000000..555860c7 --- /dev/null +++ b/docs/react-native/4x/integration/track-screen-orientation.md @@ -0,0 +1,43 @@ +--- +title: Track Screen Orientation +description: Add logging to your React Native application to track actions dispatched using the Embrace SDK +sidebar_position: 9 +--- + +# Add React Native Screen tracker + +## Adding Context to Sessions + +Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](/react-native/4x/integration/crash-reporting) and [Session Reporting](/react-native/4x/integration/session-reporting) sections. +Embrace can also collect when your app changes its orientation +Here's how you add the Orientation tracker to the session. + +## Adding the component + +Embrace has a separate module to track Screen Orientation, to use it you will need to add the Screen Orientation Tracker + +### Install the component + +```sh +yarn add @embrace-io/react-native-orientation-change-tracker +``` + +```sh +npm install @embrace-io/react-native-orientation-change-tracker +``` + +### Adding the method to your code + +Add the useEmbraceOrientationLogger to your component + +```javascript +// Import the Embrace log method +import { useEmbraceOrientationLogger } from "@embrace-io/react-native-orientation-change-tracker"; + +const App = () => { + useEmbraceOrientationLogger() + return ( + ... + ); +}; +``` \ No newline at end of file diff --git a/docs/react-native/4x/integration/upload-symbol-files.md b/docs/react-native/4x/integration/upload-symbol-files.md new file mode 100644 index 00000000..35822f56 --- /dev/null +++ b/docs/react-native/4x/integration/upload-symbol-files.md @@ -0,0 +1,227 @@ +--- +title: Uploading Symbol Files +description: Learn how to upload source maps to Embrace to translate JavaScript stack traces for your React Native application +sidebar_position: 4 +--- + +# Uploading Symbol Files + +The Embrace SDK allows you to view both native and JavaScript stack traces for crashes and error logs. +These stack traces, however, usually require symbol files to be able to make sense of them. +For JavaScript, you'll need to upload source maps. For iOS, dSYM files, and the mapping file for Android. + +## Uploading Source Maps + +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + + + + +In Xcode, find the "Bundle React Native code and images" step in the Build Phases tab. +The contents should look something like the following: + +```shell-session +export NODE_BINARY=node +../node_modules/react-native/scripts/react-native-xcode.sh +``` + +Change the contents to the following: + +```shell-session +export NODE_BINARY=node + +export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/main.jsbundle.map"; <-- Add this line + +../node_modules/react-native/scripts/react-native-xcode.sh +``` + +:::info +If you used the setup script mentioned on the [Adding the Embrace SDK](/react-native/4x/integration/add-embrace-sdk) page, this change has already been made for you. +::: + + + + By default, source maps are uploaded only for the release variant. + If you'd like to upload source maps for other variants, make the following changes: + + ```groovy + project.ext.react = [ + ... + bundleIn: true, + devDisabledIn: true, + ] + ``` + This creates a bundle and sets the debuggable flag to false. + + + +## Uploading Native And Javascript Symbol Files + + + + +## Automatic Uploads + +Automatically uploading dSYM files is a good option for you if you are not using bitcode to distribute your application. + +To enable automatic dSYM uploads, we will need to locate a number of items first: + +1. **Your App ID.** This is a 5 character code used to start Embrace. It was provided to you when you registered for an Embrace account. +1. **Your API token.** This is a longer character string. You can find it in the dashboard on the settings page, under the Tokens section. + +Now, open the "Build Phases" tab in Xcode. We will be adding a new phase. + + + +Use the "+" button on this tab to add a new "Run Script" phase. Name the phase "Embrace Symbol Uploads". + +This phase is going to be calling Embrace's `run.sh` upload script. You can configure the phase to only run on builds you want symbols uploaded to Embrace for, and skip the step on internal only builds to save time. + +The run.sh script is distributed alongside the `Embrace.framework` file. Depending on how you linked Embrace, this file will be in a different location. +See the section relevant for your integration for how to call the run script. + +Use this command format for CocoaPods integrations. + +```shell-session +REACT_NATIVE_MAP_PATH="$CONFIGURATION_BUILD_DIR/main.jsbundle.map" EMBRACE_ID=USE_YOUR_APP_ID EMBRACE_TOKEN=USE_YOUR_TOKEN "${PODS_ROOT}/EmbraceIO/run.sh" +``` + +Notice how the script's location is a reference to the CocoaPods installation folder. + +:::info +If you do not use Cocoapods please see the [Uploading dSYMs](/ios/5x/integration/dsym-upload) page from the iOS integration guide to setup automatic uploading of dSYM files in Xcode. +::: + +## Native Manual Uploads + +If your app is using bitcode or a CI system that makes accessing or modifying the build phases impossible, you can still upload your dSYM files manually. + +When applications are built with bitcode, it means the final binary and symbols only exist on Apple servers post-submission. As such you must download those symbols manually from Apple. You can do this from the Organizer window in Xcode. + + + +Once you have the dSYMs on your computer, you can upload it to Embrace using our upload utility. + +The upload utility is distributed with the Embrace SDK. See the section above on [automatically uploading dSYMs](/ios/5x/integration/dsym-upload#automatic-uploads) to learn how to locate this file in your project. You will also need your APP ID and API token. You can upload dSYM and .zip files in the same command or use the upload tool on the *Settings/Upload* dSYM tab. + +Run the upload tool and your dSYM will be sent to Embrace. + +```shell-session +# Upload a single file +/EmbraceIO/upload --app $APP_ID --token $API_TOKEN dsyms.zip + +# Upload multiple files +/EmbraceIO/upload --app $APP_ID --token $API_TOKEN --dsym my_dsym --dsym my_file.zip +``` + +This process can be scripted into your CI backend as well. Simply include the upload utility with your project's repo and call it from within the CI scripting system. + +## Javascript Manual Uploads + +When you uplad the dSYM manually you also have to upload the javascript bundle and source map files, to export them from the bundle you have to add two parameters to your build method: bundle-output and sourcemap-output + +```javascript +react-native bundle \ + --dev false \ + --platform ios \ + --entry-file index.js \ + --sourcemap-output main.map \ + --bundle-output main.bundle +``` + +```shell-session +ios/Pods/EmbraceIO/upload --app --token --rn-bundle ./build/main.jsbundle --rn-map ./build/main.map +``` + +--- + +dSYM's are complicated, but ensuring that Embrace has them will make the data you collect much more useful. Please reach out if you have any trouble with this process. + + + +Proguard files will be uploaded automatically. +If you don’t see symbolicated crashes while using Proguard, reach out to us on Slack and we’ll work with you directly. + + + + + +## Symbolication with CodePush + +If you use [App Center CodePush](https://docs.microsoft.com/en-us/appcenter/distribution/codepush/) or any other service to deploy OTA (over the air) updates, +you'll need to upload those source maps to Embrace using the upload script that ships with the iOS SDK. + +For CodePush, you'll need to generate the bundle and source map to be uploaded. +```shell-session +appcenter codepush release-react -a MyApp --output-dir ./build --sourcemap-output ./map +``` + +Then, use the Embrace upload script to upload the source map. + + + + +```shell-session +ios/Pods/EmbraceIO/upload --app --token --rn-bundle ./build/CodePush/main.jsbundle --rn-map ./map +``` + + + + +```shell-session +ios/Pods/EmbraceIO/upload --app --token --rn-bundle ./build/CodePush/index.android.bundle --rn-map ./map +``` + +:::info +The android map is generated with a different name, but the tool to upload is the same as iOS +::: + + + + +## Pointing the Embrace SDK to the JavaScript Bundle + +If you distribute changes to the JavaScript code without submitting a new version to the App Store or Google Play Store (i.e. Expo OTA updates), +you must point the Embrace SDK to where the updated JavaScript bundle will be downloaded on the device. +You can do this in either the JavaScript part or native parts of your app with the code snippet provided below. +Note that this step is unnecessary if you use CodePush since the Embrace SDK will leverage the CodePush SDK to find the location of the bundle. + + + + +```javascript +import {setJavaScriptBundlePath} from '@embrace-io/react-native'; + +setJavaScriptBundlePath(pathToBundle) +``` + + + + +```objectivec +[[RNEmbrace sharedIntance] setJavasScriptBundleURL: pathToBundle]; +``` + + + + +```java +Embrace.getInstance().getReactNativeInternalInterface().setJavaScriptBundleUrl(pathToBundle) +``` + + + + +## Expo Apps + +If your app is built using Expo and you leverage OTA to distribute updates to your users, you must manually upload source maps using the script distributed with the SDK +as described in the [Symbolication with CodePush](/react-native/4x/integration/upload-symbol-files#symbolication-with-codepush) section. + +You must also point the Embrace SDK to the location the updated bundle will be downloaded to on the device, as described in the [Pointing the Embrace SDK to the JavaScript Bundle](/react-native/4x/integration/upload-symbol-files#pointing-the-embrace-sdk-to-the-javascript-bundle). + +--- + +Now that you know how to upload symbol files to make sure stack traces are translated on the Dashboard, let's generate your first session. diff --git a/docs/react-native/changelog.md b/docs/react-native/changelog.md index a5e4f746..f6b89cbd 100644 --- a/docs/react-native/changelog.md +++ b/docs/react-native/changelog.md @@ -5,6 +5,12 @@ sidebar_position: 4 --- # React Native SDK Changelog + +## 5.0.0 +_September 26, 2024_ +* This new major version includes several backwards incompatible change, before updating please make sure you review the [upgrade guide](/react-native/upgrading/) +* Updated iOS native Embrace SDK dependency to 6.4.1. +* Deprecation of Moments in favor of Performance Tracing ## 4.3.0 _September 13, 2024_ * Fixed Android sourcemap upload issue for RN 0.72+ @@ -44,7 +50,7 @@ _March 6, 2024_ ## 4.0.1 _January 25, 2024_ * [The React Native SDK is now open source! Check it out and let us know what you think!](https://github.com/embrace-io/embrace-react-native-sdk) -* Before updating please make sure you review the [upgrade guide](/react-native/upgrading-to-4/) +* Before updating please make sure you review the [upgrade guide](/react-native/upgrading/) - Please note we've changed the package so you will need to re-install the Embrace SDK - [see details here](/react-native/integration/add-embrace-sdk/) * Updated Android native Embrace SDK dependency to 6.2.1. * Updated iOS native Embrace SDK dependency to 5.24.3. diff --git a/docs/react-native/faq.md b/docs/react-native/faq.md index 3a8419a8..6bb92812 100644 --- a/docs/react-native/faq.md +++ b/docs/react-native/faq.md @@ -25,7 +25,7 @@ Yes. We link all sessions to that user from the past and in the future. Search b ### **Do I have access to the Embrace ID at runtime?** -Yes, we make the Embrace ID available to you via `getDeviceId()` call. +Yes, we make the Embrace ID available to you via our SDK. See [these docs](/react-native/features/current-device-id-api) for more details. ## Network Requests @@ -53,4 +53,4 @@ This could be due to one of the following reasons: * Akamai * Cloudflare * PacketZoom -* You are using an Axios version that is not compatible with us or you have a custom integration that block us. You can force log the Axios request appying our [interceptor](https://github.com/embrace-io/embrace-react-native-sdk/blob/main/packages/core/src/networkInterceptors/ApplyInterceptor.ts). +* You are using an Axios version that is not compatible with us or you have a custom integration that block us. You can force log the Axios request appying our [interceptor](https://github.com/embrace-io/embrace-react-native-sdk/blob/main/packages/core/src/networkInterceptors/ApplyInterceptor.ts). \ No newline at end of file diff --git a/docs/react-native/features/current-device-id-api.md b/docs/react-native/features/current-device-id-api.md index edfdd6ea..c7340bbc 100644 --- a/docs/react-native/features/current-device-id-api.md +++ b/docs/react-native/features/current-device-id-api.md @@ -1,22 +1,10 @@ --- title: Current Device ID API -sidebar_position: 9 +sidebar_position: 4 description: Get the Device ID. --- # Current Device ID API -import GetSessionId from '@site/shared/get-session-id.md'; - - - -## Integration Steps - -In order to use this feature, you will need to follow two steps: - -1. Make sure your app is using at least version `4.0.0` of the Embrace SDK. -2. Implement the API call to obtain the current Device ID. - - ```javascript import {getDeviceId} from '@embrace-io/react-native'; @@ -27,6 +15,10 @@ const myMethod = () =>{ } ``` -import CallSupport from '@site/shared/call-support.md'; +## Overview + +Embrace SDK’s API enables customers to programmatically obtain the current Embrace Device ID. + +**When should I call the Current Device ID method?** - \ No newline at end of file +If you call the method before the SDK has started, it will return null. So, you need to call it once the SDK has been started. \ No newline at end of file diff --git a/docs/react-native/features/current-session-id-api.md b/docs/react-native/features/current-session-id-api.md index 82f1b0f3..73c5bdb6 100644 --- a/docs/react-native/features/current-session-id-api.md +++ b/docs/react-native/features/current-session-id-api.md @@ -1,23 +1,10 @@ --- title: Current Session ID API -sidebar_position: 9 +sidebar_position: 5 description: Track the current Embrace session by getting its ID. --- # Current Session ID API -import GetSessionId from '@site/shared/get-session-id.md'; - - - -## Integration Steps - -In order to use this feature, you will need to follow two steps: - -1. Make sure your app is using at least version `3.15.0` of the Embrace SDK. -2. Implement the API call to obtain the current Session ID. -3. The method will return a String with the SessionId or null if there is no active session. - - ```javascript import {getCurrentSessionId} from '@embrace-io/react-native'; @@ -28,10 +15,11 @@ const myMethod = () =>{ } ``` -:::warning Important -If you call `getCurrentSessionId()` inside the `AppState change` listener; keep in mind that this is the moment when the session is ending, and a new one is starting. Therefore, there is a high chance that you will get the session ID of the session that is still ending. You might need to delay the call or obtain the session ID at any other point of the app lifecycle to make sure the session ID you get is the one you are looking for. -::: -import CallSupport from '@site/shared/call-support.md'; +import GetSessionId from '@site/shared/get-session-id.md'; - \ No newline at end of file + + +:::warning Important +If you call `getCurrentSessionId()` inside the `AppState change` listener; keep in mind that this is the moment when the session is ending, and a new one is starting. Therefore, there is a high chance that you will get the session ID of the session that is still ending. You might need to delay the call or obtain the session ID at any other point of the app lifecycle to make sure the session ID you get is the one you are looking for. +::: \ No newline at end of file diff --git a/docs/react-native/features/identify-users.md b/docs/react-native/features/identify-users.md index 7020b640..425d6bc5 100644 --- a/docs/react-native/features/identify-users.md +++ b/docs/react-native/features/identify-users.md @@ -1,7 +1,7 @@ --- title: Identify Users description: Get to know the users of your React Native application with the Embrace SDK -sidebar_position: 2 +sidebar_position: 1 --- # Know Your Users @@ -33,9 +33,9 @@ We recommend using an anonymized or hashed user ID that only your agents can sea You can also set customized values for specific use cases or segments of users. ```javascript -import {setUserPersona} from '@embrace-io/react-native'; +import {addUserPersona} from '@embrace-io/react-native'; -setUserPersona('high_value_cart'); +addUserPersona('high_value_cart'); ``` In the above example, the session is annotated with `"high_value_cart"`. diff --git a/docs/react-native/features/index.md b/docs/react-native/features/index.md index 0f2c9304..4fb304c2 100644 --- a/docs/react-native/features/index.md +++ b/docs/react-native/features/index.md @@ -9,7 +9,9 @@ sidebar_position: 2 Embrace's SDK includes many advanced features that you can enable to help you understand more about how your application is performing in production. -1. [**Moments.**](/react-native/features/moments/) In this section you will learn how you can use Embrace to go beyond logging and crashes and start to examine critical user flows within your application. Measure performance, completion and abandonment easily and consistently. -2. [**Know your users.**](/react-native/features/identify-users/) Add your own custom identifiers to users and sessions to make sure you can aggregate and find sessions correctly. -3. [**Tracking Components.**](/react-native/features/tracking-components/) Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK. -4. [**Current Session ID API.**](/react-native/features/current-session-id-api.md) This API lets you know what the current Session Id is in case you need to track it separately. +1. [**Know your users.**](/react-native/features/identify-users/) Add your own custom identifiers to users and sessions to make sure you can aggregate and find sessions correctly. +2. [**Tracking Components.**](/react-native/features/tracking-components/) Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK. +3. [**Performance Tracing.**](/react-native/features/tracing/) Gain visibility into app operations to help debug the root cause of your mobile app's performance issues. +4. [**Current Device ID API.**](/react-native/features/current-device-id-api) This API lets you know what the current Session ID is in case you need to track it separately. +5. [**Current Session ID API.**](/react-native/features/current-session-id-api) This API lets you know what the current Embrace ID is in case you need to track it separately. +6. [**Last Run End State.**](/react-native/features/last-run-end-state) This API lets you know if the previous app instance ended in a crash. \ No newline at end of file diff --git a/docs/react-native/features/last-run-end-state.md b/docs/react-native/features/last-run-end-state.md index 2fddfcef..7b8e5e83 100644 --- a/docs/react-native/features/last-run-end-state.md +++ b/docs/react-native/features/last-run-end-state.md @@ -1,11 +1,19 @@ --- title: Last Run End State description: Understand if the previous app instance ended in a crash -sidebar_position: 10 +sidebar_position: 6 --- # Last Run End State API +```javascript + useEffect(() => { + getLastRunEndState().then(resp => { + console.log('LastRunEndState', resp); + }); + }, []); +``` + This API enables customers to automatically/programmatically understand if the previous app instance ended in a crash. Depending on your use case, having the ability to query an API to understand if the previous app instance ended in a crash will enable you to adjust the behavior or UI of your app after a crash has occurred. **What do we mean by previous app instance?** @@ -22,22 +30,6 @@ A cold launch, basically. If the app gets backgrounded/resumed so a new session 8. App is relaunched 9. `getLastRunEndState` returns "clean exit" -## Integration Steps - -In order to use this feature, you will need to follow two steps: - -1. Make sure your app is using the latest version of the Embrace SDK or at least React Native SDK 3.15.0 -2. Implement the API call after starting the SDK to receive the state of the last run. - -```javascript - useEffect(() => { - getLastRunEndState().then(resp => { - - console.log('LastRunEndState', resp); - }); - - }, []); -``` **Important Notes** @@ -46,17 +38,9 @@ In order to use this feature, you will need to follow two steps: - It will return that a crash occurred if the app crashed any time since the app last came to the foreground. This includes if the app crashed while running in the background. ::: -### Version - -This feature is included in Embrace SDK version 3.15.0 and above. - ### Possible Values ```typescript /// Used to represent the end state of the last run of the application. export type SessionStatus = 'INVALID' | 'CRASH' | 'CLEAN_EXIT'; -``` - -import CallSupport from '@site/shared/call-support.md'; - - +``` \ No newline at end of file diff --git a/docs/react-native/features/moments.md b/docs/react-native/features/moments.md deleted file mode 100644 index a4d0d7fe..00000000 --- a/docs/react-native/features/moments.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: Moments -description: Measure the performance of your React Native application using Embrace -sidebar_position: 1 ---- - -# Moments - -## Overview - -Embrace also contains a powerful stopwatch and abandonment tracking feature, which we call **moments**. -This mechanism is the same one used to measure application launch performance, which we covered in the [Session Reporting](/react-native/integration/session-reporting/) section. - -## Starting a Moment - -Here's how you start a moment. - -```javascript -import {startMoment} from '@embrace-io/react-native'; - -startMoment('addItem'); -``` - -In a sample scenario, this is a moment we're using to measure how quickly an item is added to a list after a user selects the plus button. - -You can also start a moment with **properties** and **identifier**. -For more on this, check out the [source code](/api/react-native/). - -import PropertyLimit from '@site/shared/property-limit.md'; - - - -## Ending a Moment - -Next, here's how you end a moment. - -```javascript -import {endMoment} from '@embrace-io/react-native'; - -endMoment('addItem'); -``` - -A timer is started once you make a call to start a moment. -If you end the moment within a configurable threshold, then the timer ends and the client's measurement is used to report performance. -You can end the moment from multiple locations in your app. - -## Tracking Abandonment - -In addition to measuring performance, moments can also measure abandonment. -Moments measure abandonment by default. If the moment never completes, because: - -- the user exits the app before the moment ends -- the app crashes -- an unexpected code path is taken \ No newline at end of file diff --git a/docs/react-native/features/tracing.md b/docs/react-native/features/tracing.md index bb111854..afb250a0 100644 --- a/docs/react-native/features/tracing.md +++ b/docs/react-native/features/tracing.md @@ -1,10 +1,10 @@ --- -title: Performance Tracing (Beta) +title: Performance Tracing description: Record traces to monitor the production performance and success rates of operations within your mobile app. -sidebar_position: 14 +sidebar_position: 3 --- -# Performance Tracing (Beta) +# Performance Tracing ## Overview @@ -85,7 +85,7 @@ import { startSpan } from '@embrace-io/react-native-spans'; // startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise; -const spanId = await startSpan("parentname") +const spanId = await startSpan("span-name") ``` @@ -98,7 +98,7 @@ import { startSpan } from '@embrace-io/react-native-spans'; // startSpan: (name: string, parentSpanId?: string, startTimeMs?:number) => Promise; const startTimeMs = new Date().getTime() -const spanId = await startSpan("parentname", undefined, startTimeMs) +const spanId = await startSpan("span-name", undefined, startTimeMs) ``` @@ -111,7 +111,7 @@ import { startSpan, stopSpan, addSpanAttributeToSpan } from '@embrace-io/react-n // addSpanAttributeToSpan: (spanId: string, key: string, value: string) => Promise; // Starting a span -const spanId = await startSpan("parentname") +const spanId = await startSpan("span-name") // Adding an attribute to a specific span addSpanAttributeToSpan(spanId, "myKey", "value") @@ -131,7 +131,7 @@ import { startSpan, stopSpan, addSpanEventToSpan } from '@embrace-io/react-nativ // attributes?: Attributes) => Promise; // Starting a span -const spanId = await startSpan("parentname") +const spanId = await startSpan("span-name") // Adding an event to a specific span @@ -158,7 +158,7 @@ import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; // type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown'; // Starting a span -const spanId = await startSpan("parentname") +const spanId = await startSpan("span-name") // Do something @@ -179,7 +179,7 @@ import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; // type SPAN_ERROR_CODES = 'None' | 'Failure' | 'UserAbandon' | 'Unknown'; // Starting a span -const spanId = await startSpan("parentname") +const spanId = await startSpan("span-name") try{ // Do something that throw an error @@ -197,11 +197,11 @@ try{ import { startSpan, stopSpan } from '@embrace-io/react-native-spans'; // Starting Spans -const parentSpanId = startSpan("parentname") +const parentSpanId = await startSpan("parent-name") -const firstChildSpanId = startSpan("firstchildname", parentSpanId) +const firstChildSpanId = await startSpan("firstchildname", parentSpanId) -const secondChildSpanId = startSpan("secondchildname", firstChildSpanId) +const secondChildSpanId = await startSpan("secondchildname", firstChildSpanId) // Stopping Spans stopSpan(firstChildSpanId) @@ -248,7 +248,7 @@ const attributes = { }, ]; // Starting Spans -const spanResult = await recordSpan("parentname", trackMe, attributes, events) +const spanResult = await recordSpan("span-name", trackMe, attributes, events) ``` @@ -289,7 +289,7 @@ const attributes = { const startTime = new Date().getTime() const endTime = new Date().getTime() + 1 -const spanResult = await recordCompletedSpan: ("parentname", startTime, +const spanResult = await recordCompletedSpan("span-name", startTime, endTime, "None", undefined, attributes, events) ``` diff --git a/docs/react-native/features/tracking-components.md b/docs/react-native/features/tracking-components.md index 24c19ad1..b7a6ad5f 100644 --- a/docs/react-native/features/tracking-components.md +++ b/docs/react-native/features/tracking-components.md @@ -1,7 +1,7 @@ --- title: Tracking Components description: Track the mounting and unmounting of React Components for your React Native application using the Embrace SDK -sidebar_position: 3 +sidebar_position: 2 --- # Tracking Components diff --git a/docs/react-native/integration/add-embrace-sdk.md b/docs/react-native/integration/add-embrace-sdk.md index 5dee280c..4db5e869 100644 --- a/docs/react-native/integration/add-embrace-sdk.md +++ b/docs/react-native/integration/add-embrace-sdk.md @@ -4,6 +4,11 @@ description: Add the Embrace SDK as a dependency to your React Native applicatio sidebar_position: 3 --- +```mdx-code-block +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +``` + # Adding the React Native Embrace SDK ## Add the JavaScript library @@ -15,13 +20,19 @@ yarn add @embrace-io/react-native ``` ```shell-session -npm install @embrace-io/react-native --save +npm install @embrace-io/react-native ``` :::info If you are using a yarn workspace, you must run the command at the react-native application folder level or modify package.json manually. Do not run this on your yarn workspace root. ::: +For iOS you will also need to install the pod: + +```shell +cd ios && pod install --repo-update +``` + # Adding the SDK ## Setup Script @@ -60,52 +71,11 @@ correctly. -You'll need to add an `Embrace-Info.plist` file at the root of the iOS project. - -1. Create a file called `Embrace-Info.plist` with the following content. -```xml - - - - - API_KEY - {API_KEY} - CRASH_REPORT_ENABLED - - - -``` -:::info Note for iOS -If you'd like to use Embrace's internal crash reporter, -set the `CRASH_REPORT_ENABLED` field to true in the `Embrace-Info.plist` file that you created earlier (as -described in the [Adding the Embrace SDK](/flutter/integration/add-embrace-sdk) page). -If you're using Crashlytics, set this value to false. -::: - -2. Identify your root iOS Project. - - -3. Right click on that project and select `Add Files to YOUR_PROJECT`. - +Configuration for iOS is handled in code when initializing the SDK which we will cover in the next step. If you're on +React Native version 0.60 and above you benefit from [Autolinking](https://github.com/react-native-community/cli/blob/dec33cb945be548a0d30c2ea073493e253239850/docs/autolinking.md#platform-ios) +to set up the native module so you're good to go! Otherwise review the section below: -4. Select `Embrace-Info.plist` and click on `Add`. Do not forget to select which `Targets` you are using. - - -5. Check if the file appears inside YOUR_PROJECT. - - -## React Native Version < 0.60 - -If you're on React Native version 0.60 and above, you can use [Autolinking](https://github.com/react-native-community/cli/blob/main/docs/autolinking.md) -to set up the native modules. - -```mdx-code-block -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -``` - - - +### React Native Version < 0.60 Configure your `PodFile` to add Embrace. (RN Versions < 0.6) @@ -122,11 +92,8 @@ Then, install the pod. ```shell-session cd ios && pod install --repo-update ``` - - - Update the `build.gradle` file (usually located at `/android/build.gradle`) to include the Embrace Swazzler. diff --git a/docs/react-native/integration/crash-reporting.md b/docs/react-native/integration/crash-reporting.md index 39577597..a3e7f5b1 100644 --- a/docs/react-native/integration/crash-reporting.md +++ b/docs/react-native/integration/crash-reporting.md @@ -20,13 +20,12 @@ initialize().then(hasStarted=>{ //doSomething } }); +``` + :::info Note for initialize method The initialize method will apply the interceptors needed to get information from your app. Since its a Promise, so you might want to "await" or "then" it before doing something else. ::: - -``` - This will setup a hook that gets called and uploads a crash report when the application crashes because of an unhandled JavaScript exception. You can also pass in a patch number to the `initialize` function to use along side the version of the app to pinpoint which JavaScript bundle the user was running when the app crashed. @@ -37,10 +36,35 @@ initialize({patch: 'v1'}); ``` :::info Note for iOS -If you'd like to use Embrace's internal crash reporter, -set the `CRASH_REPORT_ENABLED` field to true in the `Embrace-Info.plist` file that you created earlier (as -described in the [Adding the Embrace SDK](/react-native/integration/add-embrace-sdk) page). -If you're using Crashlytics, set this value to false. +Embrace's internal crash reporter will be used by default. If you are using another crash reporter that you don't want +to interfere with you can disable this. If you used the automated installation script or followed the manual steps for +setting up the iOS SDK then you can modify the setup in `EmbraceInitializer.swift` to remove the crash reporter: +```swift +try Embrace + .setup( + options: Embrace.Options( + appId: "YOUR-APP-ID", + platform: .reactNative, + captureServices: .automatic, + crashReporter: nil + ) + ) + .start() +``` + +If instead you only initialized the SDK through JS then the `disableCrashReporter` property can be set during the +call to initialize the SDK: +```javascript +initialize({ + sdkConfig: { + ios: { + appId: "YOUR-APP_ID", + disableCrashReporter: true, + } + } +}) +``` + ::: ```mdx-code-block diff --git a/docs/react-native/integration/index.md b/docs/react-native/integration/index.md index d00c2cf4..332dc0ec 100644 --- a/docs/react-native/integration/index.md +++ b/docs/react-native/integration/index.md @@ -22,6 +22,11 @@ This guide will walk you through integrating Embrace into your React Native appl * Gradle 7.5.1 * AGP (Android Gradle Build Tools Plugin) 7.2.2 +### iOS + +* iOS 13.0 +* Swift 5 + ### Expo For Expo apps, the project must be ejected (use `expo eject` for older versions or `expo prebuild` for newer versions) to integrate the necessary native components. diff --git a/docs/react-native/integration/next-steps.md b/docs/react-native/integration/next-steps.md index 6828e6eb..38103f24 100644 --- a/docs/react-native/integration/next-steps.md +++ b/docs/react-native/integration/next-steps.md @@ -19,11 +19,6 @@ Embrace includes many optional advanced features that can help you figure out so the most challenging issues. Learn about these features, and how to enable them, in our [Feature Reference](/react-native/features/). -## API Docs - -To see the full list of methods that the Android Embrace SDK exposes, please see -the [source repository](/api/react-native/). - ## Best Practices We offer further guides in the [Best Practices](/best-practices/) section of the docs. diff --git a/docs/react-native/integration/session-reporting.md b/docs/react-native/integration/session-reporting.md index 29639d8b..1dc049b3 100644 --- a/docs/react-native/integration/session-reporting.md +++ b/docs/react-native/integration/session-reporting.md @@ -17,7 +17,9 @@ Here are the steps you’ll be taking to create your first session. ## Initialize Embrace SDK -Initialize method applies the necessary listener to your application. This allows Embrace to track javascript errors, check js bundle changes (if you use OTA), track js patch and react native versions. +Initialize method applies the necessary listener to your application. This allows Embrace to track javascript errors, +check js bundle changes (if you use OTA), track js patch and react native versions. For iOS this is also where you'll +pass in your app ID. ```mdx-code-block import Tabs from '@theme/Tabs'; @@ -32,9 +34,15 @@ import {initialize} from '@embrace-io/react-native'; export default class App extends Component { componentDidMount() { + // Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish - - initialize().then(hasStarted=>{ + initialize({ + sdkConfig: { + ios: { + appId: "abcdf", + } + } + }).then(hasStarted=>{ if(hasStarted){ //doSomething } @@ -54,7 +62,13 @@ const App = ()=> { useEffect(()=>{ // Note: Initialize is a promise, so if you want to perform an action and it must be tracked, it is recommended to use await to wait for the method to finish - initialize().then(hasStarted=>{ + initialize({ + sdkConfig: { + ios: { + appId: "abcdf", + } + } + }).then(hasStarted=>{ if(hasStarted){ //doSomething } @@ -74,66 +88,99 @@ The initialize method will apply the interceptors that we need to get informatio ::: ## Starting Embrace SDK from Android / iOS -:::info -Initializing the Embrace SDK from React Native (Javascript) will initialize the native Embrace SDKs (Android / iOS). This means that the network, crash, and metrics interceptors will be initialized once JavaScript is loaded and has called initialize method mentioned in the previous step. This is useful only if you perform some function/have custom code before initializing the application. If you want to start applying the interceptors as soon as Android / iOS has started, you can proceed with the Native integration. +Initializing the Embrace SDK from the JavaScript side as shown above will automatically initialize the underlying native +Embrace SDKs (Android / iOS). This means that the network, crash, and metrics interceptors will only be initialized once +JavaScript is loaded and has called the initialize method mentioned in the previous step. This is useful if you want more +control over exactly when the SDK starts. However, if you want to start applying the interceptors as soon as Android / iOS +has started, or if you have custom configuration then you can perform the initialization on the native side as shown in +this section. +:::info +If you made use of the automated setup script from the [Adding the Embrace SDK](/react-native/integration/add-embrace-sdk/#setup-script) +then these steps will already have been completed for you ::: - -Start by importing the Embrace native SDK in the file that applies for each platform. - - -Open the `AppDelegate.m` file (usually located at `/ios//AppDelegate.m`) and import Embrace. -```objectivec -#import +Create a new `EmbraceInitializer.swift` file in your project with the following contents: + +```swift +import Foundation +import EmbraceIO + +@objcMembers class EmbraceInitializer: NSObject { + static func start() -> Void { + do { + try Embrace + .setup( + options: Embrace.Options( + appId: "YOUR-APP-ID", + platform: .reactNative + ) + ) + .start() + } catch let e { + print("Error starting Embrace \(e.localizedDescription)") + } + } +} ``` - - +:::warning +Once the iOS SDK is being initialized in this way any configuration any parameters passed through the JS side with +`sdkConfig.ios` are ignored. Additional configuration can be applied when setting up the iOS SDK by following [these steps](/ios/open-source/embrace-options/). +::: -Open the `MainApplication.java` file (usually located at `/android/app/src/main/java/com//MainApplication.java`) and import Embrace. +If your app delegate is in Swift you can then simply add a call `EmbraceInitializer.start()` to the start of the +`application` method in your app delegate like: -```java -import io.embrace.android.embracesdk.Embrace; +```swift +@UIApplicationMain +class AppDelegate: UIResponder, UIApplicationDelegate { + ... + func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool { + EmbraceInitializer.start() + ... ``` - - +If your app delegate is in Objective-c and this is the first swift file in your project Xcode will prompt you to create +a Bridging header file which you should accept. Then in your `AppDelegate.m|mm` file you will need to add an import to +your project's auto generated Swift header `#import "ProductModuleName-Swift.h"` substituting your product's module name +(see [Apple's docs](https://developer.apple.com/documentation/swift/importing-swift-into-objective-c#Overview) for more +information on how this is generated) and then add a call to `[EmbraceInitializer start];` to the start of the +`application` method in your app delegate like: -:::info -If you used the setup script mentioned on the [Adding the Embrace SDK](/react-native/integration/add-embrace-sdk) page, this change has already been made for you. -::: - -## Add the Start Call - -After importing Embrace, update the same files that you edited in the previous step to make a call to the Embrace SDK to start capturing data. +```objectivec +#import "AppDelegate.h" +#import "ProductModuleName-Swift.h" - - +... -```objectivec @implementation AppDelegate -- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *) launchOptions -{ - // Replace with your APP_ID, which is a 5-character value, e.g. "aBc45" - [[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkReactNative]; - return YES; -} +- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions +{ + [EmbraceInitializer start]; + ... ``` -:::info -If you are using Swift, follow the steps in the [iOS Linking Embrace](/ios/5x/integration/session-reporting) section. -::: +If you are using Expo you may need an additional `#import ` import before the line that +imports your product's auto generated header, see [this issue](https://github.com/expo/expo/issues/17705#issuecomment-1196251146) +for more details. +Open the `MainApplication.java` file (usually located at `/android/app/src/main/java/com//MainApplication.java`) +and add the following to start Embrace: + ```java +import io.embrace.android.embracesdk.Embrace; + +... + public class MainApplication extends Application implements ReactApplication { @Override @@ -148,61 +195,6 @@ public class MainApplication extends Application implements ReactApplication { -## End the Startup Moment - -Embrace automatically starts the **startup** moment when your application launches. -You'll learn more about moments in [here](/react-native/features/moments). -For now, you can think of the startup moment as a timer that measures how long it took your application to launch. -Although in both Android and iOS the moment is started automatically, ending it is platform specific. - -For Android, the SDK will end the moment automatically. -To end the startup moment when you React component mounts, see the [Android guide](/android/integration/session-reporting#end-the-startup-moment) to prevent the moment from ending automatically. - -The iOS SDK does not end the moment automatically. - -In either platform, you can end the startup moment when your application mounts. - - - - -```javascript -import {endAppStartup} from '@embrace-io/react-native'; - -export default class App extends Component { - componentDidMount() { - endAppStartup(); - } -} -``` - - - - -```javascript -import React, {useEffect, useState} from 'react' -import {endAppStartup} from '@embrace-io/react-native'; - -const App = ()=> { - - useEffect(()=>{ - endAppStartup(); - },[]) - - return ... -} -export default App -``` -:::info - -As useEffect does not block the render thread, unlike componentDidMount, it might be necessary to add a variable such as isReady to wait until all your background process are finished and the user is able to interact with the application. - -::: - - - - -End the startup moment as soon as your users are able to interact with the application. - ## Build and Run the Application Now you're ready to build and run the application. diff --git a/docs/react-native/integration/track-navigation-screens.md b/docs/react-native/integration/track-navigation-screens.md index 7e538a82..4638653b 100644 --- a/docs/react-native/integration/track-navigation-screens.md +++ b/docs/react-native/integration/track-navigation-screens.md @@ -128,20 +128,48 @@ Go to your embrace-config.json inside android/app/src/main and add the sdk_confi #### iOS: -Go to your Embrace-info.plist inside ios/YOURAPPNAME and add ENABLE_AUTOMATIC_VIEW_CAPTURE as false, your file should be like this - -```xml - - - - - API_KEY - {API_KEY} - CRASH_REPORT_ENABLED - - - ENABLE_AUTOMATIC_VIEW_CAPTURE - - - +If you used the automated installation script or followed the manual steps for setting up the iOS SDK then you can +modify the setup in `EmbraceInitializer.swift` to remove the view capture service, see [Configurating the iOS SDK](/ios/open-source/embrace-options/) +for more details: + +```swift +import Foundation +import EmbraceIO +import EmbraceCrash + +@objcMembers class EmbraceInitializer: NSObject { + static func start() -> Void { + do { + + try Embrace + .setup( + options: Embrace.Options( + appId: "YOUR-APP-ID", + platform: .reactNative, + captureServices: CaptureServiceBuilder() + .addDefaults() + .remove(ofType: ViewCaptureService.self) + .build(), + crashReporter: EmbraceCrashReporter() + ) + ) + .start() + } catch let e { + print("Error starting Embrace \(e.localizedDescription)") + } + } +} ``` + +If instead you only initialized the SDK through JS then the `disableAutomaticViewCapture` property can be set during the +call to initialize the SDK: +```javascript +initialize({ + sdkConfig: { + ios: { + appId: "YOUR-APP-ID", + disableAutomaticViewCapture: true, + } + } +}) +``` \ No newline at end of file diff --git a/docs/react-native/integration/track-screen-orientation.md b/docs/react-native/integration/track-screen-orientation.md index 7fcdc2e0..b8a7fc0b 100644 --- a/docs/react-native/integration/track-screen-orientation.md +++ b/docs/react-native/integration/track-screen-orientation.md @@ -8,7 +8,7 @@ sidebar_position: 9 ## Adding Context to Sessions -Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](https://embrace.io/docs/react-native/integration/crash-reporting) and [Session Reporting](https://embrace.io/docs/react-native/integration/session-reporting) sections. +Embrace can collect basic session data and crashes as you've already seen in the [Crash Reporting](/react-native/integration/crash-reporting) and [Session Reporting](/react-native/integration/session-reporting) sections. Embrace can also collect when your app changes its orientation Here's how you add the Orientation tracker to the session. diff --git a/docs/react-native/integration/upload-symbol-files.md b/docs/react-native/integration/upload-symbol-files.md index 5e8455fe..091d646d 100644 --- a/docs/react-native/integration/upload-symbol-files.md +++ b/docs/react-native/integration/upload-symbol-files.md @@ -10,6 +10,10 @@ The Embrace SDK allows you to view both native and JavaScript stack traces for c These stack traces, however, usually require symbol files to be able to make sense of them. For JavaScript, you'll need to upload source maps. For iOS, dSYM files, and the mapping file for Android. +:::info +If you used the setup script mentioned on the [Adding the Embrace SDK](/react-native/integration/add-embrace-sdk) page these changes has already been made for you. +::: + ## Uploading Source Maps ```mdx-code-block @@ -38,9 +42,6 @@ export SOURCEMAP_FILE="$CONFIGURATION_BUILD_DIR/main.jsbundle.map"; <-- Add this ../node_modules/react-native/scripts/react-native-xcode.sh ``` -:::info -If you used the setup script mentioned on the [Adding the Embrace SDK](/react-native/integration/add-embrace-sdk) page, this change has already been made for you. -::: @@ -70,7 +71,7 @@ Automatically uploading dSYM files is a good option for you if you are not using To enable automatic dSYM uploads, we will need to locate a number of items first: 1. **Your App ID.** This is a 5 character code used to start Embrace. It was provided to you when you registered for an Embrace account. -1. **Your API token.** This is a longer character string. You can find it in the dashboard on the settings page, under the Tokens section. +1. **Your API token.** This is a longer character string. You can find it in the dashboard on the settings page, under the API section. Now, open the "Build Phases" tab in Xcode. We will be adding a new phase. @@ -111,10 +112,10 @@ Run the upload tool and your dSYM will be sent to Embrace. ```shell-session # Upload a single file -/EmbraceIO/embrace_symbol_upload.darwin --app $APP_ID --token $API_TOKEN dsyms.zip +/EmbraceIO/embrace_symbol_upload. --app $APP_ID --token $API_TOKEN dsyms.zip # Upload multiple files -/EmbraceIO/embrace_symbol_upload.darwin --app $APP_ID --token $API_TOKEN --dsym my_dsym --dsym my_file.zip +/EmbraceIO/embrace_symbol_upload. --app $APP_ID --token $API_TOKEN --dsym my_dsym --dsym my_file.zip ``` This process can be scripted into your CI backend as well. Simply include the upload utility with your project's repo and call it from within the CI scripting system. @@ -133,7 +134,7 @@ react-native bundle \ ``` ```shell-session -ios/Pods/EmbraceIO/embrace_symbol_upload.darwin --app --token --rn-bundle ./build/main.jsbundle --rn-map ./build/main.map +ios/Pods/EmbraceIO/embrace_symbol_upload. --app --token --rn-bundle ./build/main.jsbundle --rn-map ./build/main.map ``` --- @@ -165,14 +166,14 @@ Then, use the Embrace upload script to upload the source map. ```shell-session -ios/Pods/EmbraceIO/embrace_symbol_upload.darwin --app --token --rn-bundle ./build/CodePush/main.jsbundle --rn-map ./map +ios/Pods/EmbraceIO/embrace_symbol_upload. --app --token --rn-bundle ./build/CodePush/main.jsbundle --rn-map ./map ``` ```shell-session -ios/Pods/EmbraceIO/embrace_symbol_upload.linux-amd64 --app --token --rn-bundle ./build/CodePush/index.android.bundle --rn-map ./map +ios/Pods/EmbraceIO/embrace_symbol_upload. --app --token --rn-bundle ./build/CodePush/index.android.bundle --rn-map ./map ``` :::info @@ -186,35 +187,14 @@ The Android map is generated with a different name, but the tool to upload is th If you distribute changes to the JavaScript code without submitting a new version to the App Store or Google Play Store (i.e. Expo OTA updates), you must point the Embrace SDK to where the updated JavaScript bundle will be downloaded on the device. -You can do this in either the JavaScript part or native parts of your app with the code snippet provided below. Note that this step is unnecessary if you use CodePush since the Embrace SDK will leverage the CodePush SDK to find the location of the bundle. - - - ```javascript import {setJavaScriptBundlePath} from '@embrace-io/react-native'; setJavaScriptBundlePath(pathToBundle) ``` - - - -```objectivec -[[RNEmbrace sharedIntance] setJavasScriptBundleURL: pathToBundle]; -``` - - - - -```java -Embrace.getInstance().getReactNativeInternalInterface().setJavaScriptBundleUrl(pathToBundle) -``` - - - - ## Expo Apps If your app is built using Expo and you leverage OTA to distribute updates to your users, you must manually upload source maps using the script distributed with the SDK diff --git a/docs/react-native/upgrading-to-4.md b/docs/react-native/upgrading-to-4.md deleted file mode 100644 index 76ea4e5c..00000000 --- a/docs/react-native/upgrading-to-4.md +++ /dev/null @@ -1,34 +0,0 @@ -# Upgrade guide - -# Upgrading to 4.x - -## Updated Embrace Package -Please note we've changed the package so you will need to install the new Embrace SDK - [see details here](/react-native/integration/add-embrace-sdk/) - -## Asyncronous methods (Promises) -Since version 4.0, all our methods promises. Therefore, if you need to retrieve a value, such as the session ID, you should use await/then to wait for the response. - -## Replace usage of deprecated methods with new ones - -Version 4.0 of the Embrace React Native SDK renames some functions. This has been done to reduce -confusion & increase consistency across our SDKs. - - -| Old API | New API | Comments | -|-------------------------------------------------------|---------------------------------------------------------------------|:----------------------------------------------------------------------| -| `setUserPersona(String)` | `addUserPersona(String)` | Renamed function to better describe functionality. | -| `logBreadcrumb(String)` | `addBreadcrumb(String)` | Renamed function to better describe functionality. | -| `startEvent()` | `startMoment(String)` | Renamed function to better describe functionality. | -| `endEvent()` | `endMoment(String)` | Renamed function to better describe functionality. | -| `logInfo(String, ...)` | `logMessage(...)` | Altered function signature to standardise behavior. | -| `logWarning(String, ...)` | `logMessage(...)` | Altered function signature to standardise behavior. | -| `logError(String, ...)` | `logMessage(...)` | Altered function signature to standardise behavior. | -| `logNetworkCall()` | `recordNetworkRequest(...)` | Renamed function to better describe functionality. | -| `logNetworkRequest()` | `recordNetworkRequest(...)` | Renamed function to better describe functionality. | - -### Previously deprecated APIs that have been removed - -| Old API | Comments | -|---------------------------------------------|----------------------------------------------------------| -| `startMomentAllowingScreenshot` | Deprecated API that is no longer supported. | -| `logMessage(..., allowScreenshot)` | Deprecated API that is no longer supported. | diff --git a/docs/react-native/upgrading.md b/docs/react-native/upgrading.md new file mode 100644 index 00000000..360da21a --- /dev/null +++ b/docs/react-native/upgrading.md @@ -0,0 +1,91 @@ +--- +title: Upgrade Guide +sidebar_position: 5 +description: Upgrade guide for Embrace React Native SDK versions +--- + +# Upgrade guide + +# Upgrading from 4.x to 5.x + +:::info 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](/react-native/integration/)) +::: + +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 + +```shell +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: + +```javascript +import React, {useEffect, useState} from 'react' +import {initialize} from '@embrace-io/react-native'; + +const App = ()=> { + + useEffect(()=>{ + initialize({ + sdkConfig: { + ios: { + appId: "YOUR_IOS_APP_ID", + } + } + }).then(hasStarted=>{ + if(hasStarted){ + //doSomething + } + }); + },[]) + + 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: + +```objectivec +[[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkReactNative]; +``` + +Or in Swift a line such as: + +```swift +Embrace.sharedInstance().start(launchOptions: launchOptions, framework:.reactNative) +``` + +Replace these with the updated initialization code outlined in [Starting Embrace SDK from Android / iOS](/react-native/integration/session-reporting/#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](/react-native/features/tracing/) for more information. + +## Removed 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. | \ No newline at end of file diff --git a/static/images/android-integration.png b/static/images/android-integration.png index 2bee6f22..4e287343 100644 Binary files a/static/images/android-integration.png and b/static/images/android-integration.png differ