Embrace Documentation

https://embrace.io/docs
Admin
Embrace provides mobile monitoring to elevate user experience, offering features like crash...
Tokens:185,091
Snippets:1,204
Trust Score:9.9
Update:1 year ago
Show doc for...
Tokens:
Raw
### SDK Initialization and Starting

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

The SDK initialization process has been split into two steps in 6.x: `setup(options)` for configuration and `start()` to begin operation. This allows for more control over when the SDK becomes active, replacing the single `startWithLaunchOptions` method.

```APIDOC
setup(options: LaunchOptions)
  Configures the Embrace SDK with provided launch options.
  start()
  Initiates the Embrace SDK's operation after setup.
  Replaces: startWithLaunchOptions(launchOptions:)
  Usage:
    let options = Embrace.LaunchOptions(...)
    Embrace.setup(options: options)
    Embrace.start()
  Parameters:
    setup(options:):
      options: An instance of Embrace.LaunchOptions containing configuration.
    start():
      None
  Returns:
    Void
```

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

### Basic Setup and Start

Source: https://embrace.io/docs/ios/6x/api-reference/embrace-client

Illustrates the fundamental steps for setting up and starting the Embrace SDK in an iOS application. It includes error handling for the setup process.

```swift
import EmbraceIO
import SwiftUI

struct NewEmbraceApp: App {
    init() {
        do {
            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "YOUR_APP_ID"
                        // Other configuration options
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}
```

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

### Unity Integration Guide

Source: https://embrace.io/docs/unity/integration/integration-steps

Comprehensive guide for integrating Embrace into Unity projects. Covers initial setup, platform-specific configurations, session reporting, crash handling, breadcrumbs, and logging.

```APIDOC
Unity Integration:
  __overview__
    Guides users through the process of integrating Embrace SDK into Unity projects for performance monitoring.

  __integration-steps__
    Details the step-by-step process for linking Embrace within a Unity project.

  __linking-embrace__
    Specific instructions on how to link the Embrace SDK to your Unity project.

  __configure-ios-platform__
    Configuration steps for the iOS platform within Unity.
    - Ensure correct build settings and dependencies are met.

  __configure-android-platform__
    Configuration steps for the Android platform within Unity.
    - Ensure correct build settings and dependencies are met.

  __login-embrace-dashboard__
    Instructions on how to log in to the Embrace Dashboard to view collected data.

  __session-reporting__
    Details on how Embrace captures and reports user sessions.
    - Includes information on session start/end events and duration.

  __crash-reporting__
    Information on setting up and receiving crash reports from Unity applications.
    - Covers symbolication and crash data collection.

  __breadcrumbs__
    Guidance on implementing and using breadcrumbs for tracing user activity.
    - Useful for debugging issues leading up to a crash or error.

  __log-message-api__
    API for sending custom log messages to Embrace.
    - `Embrace.Log(message: string, level: LogLevel)`
    - `LogLevel`: `Info`, `Warning`, `Error`

  __next-steps__
    Recommendations for further actions after initial integration.

  __unity-cloud-build-compatibility__
    Information regarding compatibility with Unity Cloud Build.
    - Specific configurations or known issues for CI/CD pipelines.
```

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

### Verify Installation and Get Help

Source: https://embrace.io/docs/ios/5x/integration/cli-tool

Confirms the installation of the `embtool` binary by checking its path and displays the general help information for the tool.

```shell
which embtool
/usr/local/bin/embtool

embtool --help
OVERVIEW: A command line tool to help with Embrace integration
```

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

### Install Embrace Web SDK

Source: https://embrace.io/docs/web/getting-started/basic-setup

Installs the Embrace Web SDK package using either npm or yarn. This is the first step to integrate Embrace into your web application.

```npm
npm install @embrace-io/web-sdk
```

```yarn
yarn add @embrace-io/web-sdk
```

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

### Initialize Embrace SDK in SwiftUI

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Demonstrates how to initialize and start the Embrace SDK within a SwiftUI application. It shows the use of `Embrace.setup()` with `Embrace.Options` to configure the SDK using an App ID. The setup is performed within the application's initializer to ensure it runs as early as possible.

```Swift
import EmbraceIO
import SwiftUI

struct NewEmbraceApp: App {
    init() {
        do {
            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "YOUR_APP_ID"  // Your App ID from Embrace Dashboard
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}
```

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

### Initialize Embrace in AppDelegate

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Sets up and starts the Embrace SDK within the AppDelegate for UIKit applications. Requires an App ID and handles potential setup errors using a do-catch block.

```swift
import EmbraceIO
import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        do {
            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "YOUR_APP_ID"  // Your App ID from Embrace Dashboard
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }

        return true
    }
}
```

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

### Checking Embrace SDK Status

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Illustrates how to check the current status of the Embrace SDK using the `state` property, which provides more detailed information than the deprecated `started` property.

```swift
switch Embrace.client?.state {
case .started:
    // SDK is running
case .initialized:
    // SDK is initialized but not started
case .notInitialized, nil:
    // SDK failed to initialize or hasn't been initialized yet
}
```

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

### Session Management Examples

Source: https://embrace.io/docs/ios/6x/api-reference/embrace-client

Provides examples for managing application sessions with the Embrace SDK. It covers checking the SDK state, retrieving the current session ID, and manually ending or starting sessions.

```swift
// Check SDK state
switch Embrace.client?.state {
case .started:
    print("SDK is running")
    // Get current session ID
    if let sessionId = Embrace.client?.currentSessionId() {
        print("Current session: \(sessionId)")
    }
case .initialized:
    print("SDK is initialized but not started")
case .notInitialized, nil:
    print("SDK not initialized")
case .stopped:
    print("SDK has been stopped")
}

// Manual session control
Embrace.client?.endCurrentSession()
Embrace.client?.startNewSession()
```

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

### Custom App Startup Tracking with Embrace 6.X Traces

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

Provides an example of custom app startup tracking in Embrace 6.X. It shows how to create a root "app-startup" span and child spans for key initialization events like "database-initialization", allowing for comprehensive measurement of the startup process.

```Swift
// Example of custom app startup tracking
let startupSpan = Embrace.client?.buildSpan(name: "app-startup")
                          .startSpan()

// Record child spans for important startup events
let databaseInitSpan = Embrace.client?.buildSpan(name: "database-initialization")
                              .setParent(startupSpan)
                              .startSpan()
// Initialize database
databaseInitSpan?.end()

// Add more child spans for other initialization components
// ...

// End the startup span when the app is fully loaded
startupSpan?.end()
```

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

### Initialize Embrace iOS SDK v6.x in Swift

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

Demonstrates how to initialize the Embrace Apple SDK v6.x programmatically in Swift. This replaces the previous .plist file configuration and uses an Embrace.Options object for setup.

```swift
import EmbraceIO
import SwiftUI

struct NewEmbraceApp: App {
    init() {
        do {
            try Embrace
                .setup(
                    options: Embrace.Options(
                        appId: "12345",
                        logLevel: .default,
                        crashReporter: EmbraceCrashReporter(),
                        // Other configuration options
                    )
                )
                .start()
        } catch let e {
            print("Error starting Embrace \(e.localizedDescription)")
        }
    }
}
```

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

### Embrace 6.X Full Trace Usage

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

Illustrates the more detailed approach to using traces in Embrace 6.X by manually building, starting, and ending a `Span` object. This method provides more control over span creation and lifecycle.

```Swift
/* ******************************* */
// Using Traces in Embrace 6.x (full)
let span = Embrace.client?.buildSpan(name: "add-cart-item")
                .startSpan()
// Perform add cart logic
span?.end()
```

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

### Embrace 5.X Moments vs 6.X Shorthand Traces

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

Demonstrates the transition from using `startMoment`/`endMoment` in Embrace 5.X to the shorthand `recordSpan` in Embrace 6.X for tracing operations. Shows how to start and end a trace for a specific action like "add-cart-item".

```Swift
/* ******************************* */
// Using Moments in Embrace 5.X
Embrace.sharedInstance().startMoment(withName: "add-cart-item")
// Perform add cart logic
Embrace.sharedInstance().endMoment(withName: "add-cart-item")

/* ******************************* */
// Using Traces in Embrace 6.X (shorthand)
Embrace.recordSpan(name: "add-cart-item") { span in
    // perform add cart logic
}
```

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

### Embrace Client API Reference (Swift)

Source: https://embrace.io/docs/ios/6x/api-reference/embrace-client

Provides details on the Embrace Client class, its static setup and access methods, and instance methods for starting and checking the SDK state. Includes parameter descriptions, return values, and error conditions.

```swift
Embrace Client API Reference:

Embrace Class:
  The main interface for interacting with the Embrace SDK.

Static Methods:
  setup(options: Embrace.Options) throws -> Embrace
    - Sets up the Embrace SDK with the provided options.
    - Parameters:
      - options: An instance of Embrace.Options that configures the SDK.
    - Returns: An instance of Embrace that can be used to start the SDK and interact with it.
    - Throws: An error if the SDK cannot be initialized properly, typically due to storage issues.

  client: Embrace?
    - Provides access to the singleton instance of the Embrace class after it has been set up.
    - Returns: The singleton Embrace instance, or nil if not yet set up.

Instance Methods:
  start() throws -> Embrace
    - Starts the Embrace SDK, initiating data collection and session tracking.
    - Returns: The same Embrace instance for method chaining.
    - Throws: An error if the SDK cannot be started properly.

  state: EmbraceSDKState { get }
    - Returns the current state of the SDK.
    - Returns: The current SDK state, which can be:
      - .notInitialized - SDK hasn't been set up yet
      - .initialized - SDK is set up but not started
      - .started - SDK is running and collecting data
      - .stopped - SDK has been stopped

  started (Deprecated): Bool { get }
    - Returns true if the SDK has been started, false otherwise.
    - Note: This property is deprecated. Use the `state` property instead for more detailed status information.
```

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

### Handle Embrace SDK Initialization Errors

Source: https://embrace.io/docs/ios/6x/best-practices/debugging-tips

Shows how to properly initialize the Embrace SDK using `setup` and `start`, including error handling and logging additional debug information for initialization failures. It also advises verifying the App ID and checking console logs.

```swift
do {
    try Embrace
        .setup(options: options)
        .start()
} catch let error {
    print("Embrace SDK failed to initialize: \(error.localizedDescription)")
    // Log additional debug information
    print("Options used: \(String(describing: options))")
}
```

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

### Accessing the Embrace Client Instance

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Provides two methods for accessing the Embrace client instance after successful setup: storing the reference from the setup call or using the static client property.

```swift
// Method 1: Store reference from setup
let embrace = try Embrace
    .setup(options: embraceOptions)
    .start()

// Later in your code
embrace.buildSpan(name: "my-operation", type: .performance).startSpan()

// Method 2: Use static client property
// After setup has been called
Embrace.client?.buildSpan(name: "my-operation", type: .performance).startSpan()
```

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

### Check SDK State

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

The boolean property `isStarted` for checking if the SDK has been initialized and started is now represented by comparing the `state` property to the `.started` enum case. This offers a more explicit way to determine the SDK's operational status.

```APIDOC
state == .started
  Checks if the Embrace SDK is currently in the started state.
  Replaces: isStarted (boolean property)
  Usage:
    if Embrace.state == .started {
      // SDK is running
    } else {
      // SDK is not running
    }
  Parameters:
    state: The current state of the Embrace SDK.
    .started: An enum case representing the active state.
  Returns:
    Boolean: true if the SDK is started, false otherwise.
```

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

### Manage User Consent for Embrace Setup (Swift)

Source: https://embrace.io/docs/ios/6x/best-practices/security-considerations

Demonstrates how to conditionally start the Embrace SDK based on user consent for privacy regulations like GDPR and CCPA. It shows setting up Embrace with default or limited options.

```Swift
func updatePrivacyConsent(userConsented: Bool) {
    if userConsented {
        // Start Embrace with user consent
        try? Embrace.setup(options: options).start()
    } else {
        // If user does not consent, don't start Embrace
        // or limit what you collect
        try? Embrace.setup(options: limitedOptions).start()
    }
}
```

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

### Trace Multi-Step Processes with Swift Spans

Source: https://embrace.io/docs/ios/6x/best-practices/common-patterns

Demonstrates creating parent and child spans for complex user flows like checkout. This example shows how to start spans, set attributes, and log business events for detailed process monitoring.

```swift
class CheckoutCoordinator {
    private var checkoutSpan: Span?

    func startCheckout() {
        // Start a parent span for the whole checkout flow
        checkoutSpan = Embrace.client.startSpan(name: "checkout_flow")
        checkoutSpan?.setAttribute(key: "cart_value", value: cart.totalValue)
        checkoutSpan?.setAttribute(key: "items_count", value: cart.items.count)

        navigateToShippingScreen()
    }

    func navigateToShippingScreen() {
        // Child span for the shipping step
        let shippingSpan = Embrace.client.startSpan(name: "checkout_shipping", parent: checkoutSpan)
        // Show shipping screen
        // ...
        shippingSpan.end()
    }

    func navigateToPaymentScreen() {
        // Child span for the payment step
        let paymentSpan = Embrace.client.startSpan(name: "checkout_payment", parent: checkoutSpan)
        // Show payment screen
        // ...
        paymentSpan.end()
    }

    func completeCheckout(success: Bool) {
        // Record the outcome
        checkoutSpan?.setAttribute(key: "checkout_success", value: success)

        // Log a business event
        if success {
            Embrace.client.logMessage("Checkout completed successfully",
                                      severity: .info,
                                      attributes: ["order_id": orderId])
        } else {
            Embrace.client.logMessage("Checkout failed",
                                      severity: .warning,
                                      attributes: ["failure_reason": failureReason])
        }

        // End the parent span
        checkoutSpan?.end()
        checkoutSpan = nil
    }
}

```

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

### Embrace SDK: Setup Script

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

Information on the setup script provided to help integrate the SDK into new projects.

```APIDOC
Embrace SDK Setup Script:

Integration script:
  - Adds a setup script to help users integrate more easily on new projects (version 3.3.0).
  - Usage: After installing the SDK, run `node node_modules/react-native-embrace/dist/scripts/setup/run.js`.
  - Fixed setup script (version 3.9.21).
```

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

### Embrace-Info.plist Configuration Example

Source: https://embrace.io/docs/ios/5x/features/configuration-file

An example of the Embrace-Info.plist file used to configure the Embrace SDK for iOS. It includes common settings like API key and network capture limits, placed at the root of the IPA.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>API_KEY</key>
	<string>TEST_KEY</string>
	<key>CRASH_REPORT_PROVIDER</key>
	<string>embrace</string>
	<key>NETWORK</key>
	<dict>
		<key>DEFAULT_CAPTURE_LIMIT</key>
		<integer>1000</integer>
		<key>DOMAINS</key>
		<dict>
			<key>example.com</key>
			<integer>10</integer>
		</dict>
	</dict>
</dict>
</plist>
```

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

### Run Embrace SDK Setup Scripts

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

Executes setup scripts to automatically modify project files and add native dependencies for Android and iOS Embrace SDK integration.

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

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

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

### Add and Start Log Exporters

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

Demonstrates how to add configured log record exporters to the Embrace SDK and start the SDK. Exporters must be added before starting the SDK.

```kotlin
Embrace.getInstance().addLogRecordExporter(SystemOutLogRecordExporter.create())
Embrace.getInstance().addLogRecordExporter(customDockerLogRecordExporter)
Embrace.getInstance().addLogRecordExporter(grafanaCloudLogRecordExporter)

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

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

### Swift: Start, Attribute, and End Custom Span

Source: https://embrace.io/docs/ios/6x/manual-instrumentation

Demonstrates how to manually create a span using the Embrace SDK, add attributes for context, and properly end the span, handling both success and error cases. Requires an initialized Embrace client.

```swift
let span = Embrace.client?.startSpan(name: "important_operation")

// Perform your operation
// ...

// Add some context to the span
span?.setAttribute(key: "operation_size", value: "large")

// Record success or failure
if success {
    span?.end()
} else {
    span?.recordError(error)
    span?.setStatus(.error)
    span?.end()
}
```

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

### CocoaPods Installation

Source: https://embrace.io/docs/ios/6x/getting-started/installation

Standard installation of the Embrace SDK using CocoaPods. This adds the main EmbraceIO pod to your project, including all necessary components for basic SDK functionality.

```ruby
pod 'EmbraceIO', '~> 6.9.1'
```

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

### View Embrace Setup Changes with Git

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

Displays the differences made to project files by the Embrace setup scripts. This is useful for verifying the integration and understanding the changes.

```shell
git diff
```

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

### Wrap SDK Calls with onReady (Async CDN)

Source: https://embrace.io/docs/web/getting-started/basic-setup

Explains the necessity of wrapping early SDK calls within the `onReady` method when using asynchronous CDN loading to ensure the SDK is initialized before execution.

```javascript
window.EmbraceWebSdkOnReady.onReady(() => {
   window.EmbraceWebSdk.sdk.initSDK({
      appVersion: '0.0.1',
      /*...*/
   });
})
```

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

### Install latest Cocoapods

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

After updating package dependencies, it's recommended to install the latest Cocoapods version for your iOS project to ensure compatibility and include all necessary native modules.

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

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

### Install Embrace Web CLI (yarn)

Source: https://embrace.io/docs/web/getting-started/sourcemap-uploads

Installs the Embrace Web CLI tool as a development dependency using yarn. This CLI is essential for uploading sourcemap files to enable symbolication.

```bash
yarn add -D @embrace-io/web-cli
```

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

### Initialize SDK with Verbose Logging

Source: https://embrace.io/docs/web/getting-started/basic-setup

Demonstrates how to configure the SDK's logging level during initialization. Setting `logLevel` to `sdk.DiagLogLevel.INFO` enables more detailed console output for debugging purposes.

```javascript
import { sdk } from '@embrace-io/web-sdk';

sdk.initSDK({
  appID: "YOUR_EMBRACE_APP_ID",
  appVersion: "YOUR_APP_VERSION",
  logLevel: sdk.DiagLogLevel.INFO,
});
```

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

### Get Last Run End State Example

Source: https://embrace.io/docs/react-native/4x/features/last-run-end-state

Example of how to call the `getLastRunEndState` function within a React Native component's `useEffect` hook to retrieve and log the status of the previous app session.

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

function App() {
  useEffect(() => {
    getLastRunEndState().then(resp => {
      console.log('LastRunEndState', resp);
    });
  }, []);

  return (
    // Your app content
    null
  );
}
```

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

### Run React Native Embrace iOS Setup Script

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

Executes the setup script to automatically modify project files for integrating Embrace native iOS dependencies. This script is located within the installed node_modules.

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

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

### Initialize SDK with App Version (CDN)

Source: https://embrace.io/docs/web/getting-started/basic-setup

Illustrates how to initialize the SDK when loaded from a CDN, specifically requiring the `appVersion` to be passed during initialization as the CLI tool cannot inject it.

```javascript
sdk.initSDK({
  appVersion: '0.0.1',
  /*...*/
});
```

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

### Include SDK via CDN

Source: https://embrace.io/docs/web/getting-started/basic-setup

Demonstrates how to include the Embrace.io Web SDK directly from a CDN using a script tag in the HTML head. This makes the SDK available as a global `EmbraceWebSdk` object.

```html
<script src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk@X.X.X"></script>
```

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

### Run React Native Embrace Android Setup Script

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

Executes the setup script to automatically modify project files for integrating Embrace native Android dependencies. This script is located within the installed node_modules.

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

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

### Adapt Import for CDN Usage

Source: https://embrace.io/docs/web/getting-started/basic-setup

Shows how to adjust code when using the SDK from a CDN, changing imports from node modules to referencing the global `window.EmbraceWebSdk` object.

```javascript
- import { sdk } from '@embrace-io/web-sdk';
+ const { sdk } = window.EmbraceWebSdk;
```

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

### Install Embrace Web CLI (npm)

Source: https://embrace.io/docs/web/getting-started/sourcemap-uploads

Installs the Embrace Web CLI tool as a development dependency using npm. This tool is required for uploading sourcemap files to the Embrace platform.

```bash
npm install --save-dev @embrace-io/web-cli
```

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

### Get SDK Enabled Status

Source: https://embrace.io/docs/ios/6x/api-reference/embrace-client

Retrieves a boolean value indicating whether the Embrace SDK is currently started and has not been disabled via remote configurations. This property is read-only.

```Swift
var isSDKEnabled: Bool { get }
```

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

### Embrace SDK Initialization Options

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Demonstrates common configuration options for the Embrace SDK during initialization, including App ID, App Group ID, log level, and OpenTelemetry export.

```swift
Embrace.Options(
    appId: "YOUR_APP_ID",         // Required for sending data to Embrace
    appGroupId: "group.your.id",  // Optional: for app extensions sharing data
    logLevel: .default,           // Controls SDK's console logging verbosity
    export: nil                   // Optional: for OpenTelemetry export
)
```

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

### Embrace iOS SDK 5.x FAQ

Source: https://embrace.io/docs/ios/5x/integration/next-steps

A collection of frequently asked questions regarding the Embrace iOS SDK, offering quick solutions and clarifications for common queries.

```apidoc
APIDOC:
  FAQ:
    Description: Frequently asked questions for the Embrace iOS SDK.
    Purpose: Provide answers to common user queries.
    Link: /docs/ios/faq/
    Related: Feature Reference, Best Practices
```

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

### Embrace iOS SDK Best Practices

Source: https://embrace.io/docs/ios/5x/integration/next-steps

Offers guidance and recommendations for effectively using the Embrace iOS SDK, helping users make informed decisions to maximize the platform's benefits.

```apidoc
APIDOC:
  Best Practices:
    Description: Guides and recommendations for optimal usage of the Embrace iOS SDK.
    Purpose: Help users make informed decisions and maximize Embrace benefits.
    Link: /docs/best-practices/
    Related: Feature Reference, FAQ
```

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

### Working with Spans Code Example

Source: https://embrace.io/docs/ios/6x/api-reference/utility-classes

Demonstrates how to create, customize, start, add events to, and end a span using the Embrace SDK, illustrating the lifecycle of a performance span.

```swift
// Create and customize a span
let span = Embrace.client?.buildSpan(name: "checkout-process", type: .performance)
    .setAttribute("order_id", value: orderId)
    .setAttribute("total_amount", value: totalAmount)
    .startSpan()

// Perform the work
performCheckoutProcess()

// Add events during the span
span?.addEvent("payment-started", attributes: ["payment_provider": "stripe"])

// End the span when complete
span?.end()

```

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

### Handle Embrace SDK Initialization Errors

Source: https://embrace.io/docs/ios/6x/getting-started/basic-setup

Shows how to handle potential errors during Embrace SDK setup and startup using optional try for silent failure or a do-catch block for explicit error handling.

```swift
// Optional try for silent failure
try? Embrace
    .setup(options: Embrace.Options(appId: "YOUR_APP_ID"))
    .start()

// Later in your code
// If setup failed, this will simply not create a span
let span = Embrace.client?.buildSpan(
    name: "user-action",
    type: .performance
).startSpan()
// ...
span?.end()
```

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

### Get Current Session ID

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

The method to retrieve the current session's unique identifier has been updated from `getCurrentSessionId()` to `currentSessionId()`. This change reflects a more direct property-like access to session information.

```APIDOC
currentSessionId()
  Retrieves the unique identifier for the current Embrace session.
  Replaces: getCurrentSessionId()
  Usage:
    let sessionId = Embrace.currentSessionId()
    print("Current session ID: \(sessionId ?? "N/A")")
  Parameters:
    None
  Returns:
    Optional String: The current session ID, or nil if no session is active.
```

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

### Check Last Run State (C#)

Source: https://embrace.io/docs/unity/features/last-run-end-state

Example demonstrating how to start the Embrace SDK and retrieve the state of the last application run to determine if it ended in a crash.

```C#
// The SDK must be started before checking the last run end state
Embrace.Instance.StartSDK();
bool didCrashLastRun = Embrace.Instance.GetLastRunEndState() == LastRunEndState.Crash;

```

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

### Start Embrace Span

Source: https://embrace.io/docs/ios/6x/core-concepts/traces-spans

Demonstrates how to build and start a new span using the Embrace SDK. It shows both a two-step and a one-line approach for creating a span with a given name.

```Swift
let spanBuilder = Embrace
            .client?
            .buildSpan(name: "process-image")

let span = spanBuilder.startSpan()

// Or in one line
let span = Embrace
            .client?
            .buildSpan(name: "process-image")
            .startSpan()
```

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

### View Git Changes After Setup

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

Uses Git to display the differences made to your project files by the Embrace SDK setup scripts. This is useful for verifying the integration or understanding the changes.

```git
git diff
```

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

### Enable Unhandled Promise Rejection Tracking

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

Unhandled promise rejection tracking is now an opt-in feature. You must explicitly enable this functionality in your Embrace SDK setup to receive reports.

```javascript
import Embrace from '@embrace-io/react-native';

Embrace.configure({
  // ... other configurations
  enableUnhandledPromiseRejectionTracking: true
});
```

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

### Embrace React Native SDK Integration Guide

Source: https://embrace.io/docs/react-native/5x/integration/crash-reporting

Steps to integrate the Embrace SDK into a React Native application for crash reporting and performance monitoring. Covers essential setup and configuration.

```react-native
This section outlines the integration steps for the Embrace React Native SDK, including:
- Adding the Embrace SDK dependency.
- Configuring project settings for iOS and Android.
- Uploading symbol files for deobfuscating crash reports.
- Setting up session reporting and crash reporting.
- Utilizing features like breadcrumbs and screen tracking.
```

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

### Datadog Integration Setup

Source: https://embrace.io/docs/data-destinations/data-dog-setup

This section outlines the prerequisites and steps required to integrate Embrace with Datadog. It covers obtaining the necessary Datadog API Key and Site URL, which are essential for configuring data forwarding.

```APIDOC
Datadog Integration:
  Purpose: Configure Embrace to forward data to Datadog.

  Prerequisites:
    - An active Datadog account.

  Steps:
    1. Pulling your Datadog API Key:
       - Log into your Datadog account.
       - Navigate to Organization Settings > API Keys.
       - Locate the 'Key' field (not 'Key ID').
       - Click the 'Copy' button to retrieve the API key.
       - Reference: [Datadog documentation](https://docs.datadoghq.com/account_management/api-app-keys/#add-an-api-key-or-client-token)

    2. Pulling your Datadog Site URL:
       - Navigate to your Datadog account dashboard.
       - The 'SITE URL' is displayed at the top of the page (e.g., https://us5.datadoghq.com).
       - Use this URL for configuration.

  Related Integrations:
    - Chronosphere Integration
    - Elastic Integration
    - Grafana Cloud Integration
    - Honeycomb Integration
    - New Relic Integration
    - Observe Integration
    - Splunk Integration
```

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

### Remove Legacy Embrace SDK Initialization (Swift)

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

Example of the legacy Swift code that should be removed from your AppDelegate files when upgrading the Embrace SDK. This line typically initiated the SDK with framework information.

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

```

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

### Embrace Apple SDK Package Products

Source: https://embrace.io/docs/ios/6x/getting-started/installation

An overview of the different package products available within the Embrace Apple SDK, detailing their purpose and recommended usage for integration.

```APIDOC
Embrace Apple SDK Package Products:

- EmbraceIO:
  - Description: The recommended product for quick integration. Provides a convenience layer over EmbraceCore to simplify setup.
  - Usage: Recommended for most straightforward installations.

- EmbraceCore:
  - Description: The main implementation of the Embrace SDK. Allows for customization of integration.
  - Usage: For developers needing custom integration setups.

- EmbraceCrash:
  - Description: Contains the Embrace Crash Reporter. Kept separate for apps that may not want crash reporting or prefer a different reporter.
  - Dependencies: Included as a dependency of EmbraceIO, but not EmbraceCore.

- EmbraceCrashlyticsSupport:
  - Description: Enables Crashlytics/Firebase as the primary crash reporter. Embrace mirrors reports sent to Crashlytics for availability in the Embrace Dashboard.
  - Usage: Optional for users needing Crashlytics as their primary reporter while leveraging the Embrace Dashboard.

- EmbraceSemantics:
  - Description: Contains constants and attributes used internally to extend OTel Semantic Conventions.
  - Usage: For advanced integrations involving OpenTelemetry semantic conventions.
```

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

### Remove Legacy Embrace SDK Initialization (Objective-C)

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

Example of the legacy Objective-C code that should be removed from your AppDelegate files when upgrading the Embrace SDK. This line typically initiated the SDK with framework information.

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

```

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

### Async CDN Loading Snippet

Source: https://embrace.io/docs/web/getting-started/basic-setup

Provides a JavaScript snippet for asynchronously loading the Embrace.io Web SDK to prevent page rendering blockage. It uses a queue (`EmbraceWebSdkOnReady`) to manage SDK calls before it's fully loaded.

```javascript
!function(){window.EmbraceWebSdkOnReady=window.EmbraceWebSdkOnReady||{q:[],onReady:function(e){window.EmbraceWebSdkOnReady.q.push(e)}};let e=document.createElement("script");e.async=!0,e.src="https://cdn.jsdelivr.net/npm/@embrace-io/web-sdk@X.X.X",e.onload=function(){window.EmbraceWebSdkOnReady.q.forEach(e=>e()),window.EmbraceWebSdkOnReady.q=[],window.EmbraceWebSdkOnReady.onReady=function(e){e()}};let n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(e,n)}();
```

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

### Direct Span Manipulation

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

The method `stopSpanWithId` is no longer necessary in 6.x. Instead, developers should directly use the `end()` method on the existing `Span` object that was obtained when the span was started. This simplifies span lifecycle management.

```APIDOC
span.end()
  Ends the execution of the Span, recording its duration and attributes.
  Replaces: stopSpanWithId(spanId:)
  Usage:
    let span = Embrace.buildSpan(name: "operation").startSpan()
    // ... perform operation ...
    span.end() // Directly end the span instance
  Parameters:
    end():
      None
  Returns:
    Void
```

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

### Embrace iOS SDK 5.x Feature Reference

Source: https://embrace.io/docs/ios/5x/integration/next-steps

Provides access to advanced features of the Embrace iOS SDK, detailing how to enable and utilize them for deeper insights into application performance and issues.

```apidoc
APIDOC:
  Feature Reference:
    Description: Comprehensive guide to advanced optional features for the Embrace iOS SDK.
    Purpose: Learn about and enable features to diagnose complex issues.
    Link: /docs/ios/5x/features/
    Related: Integration Guide, FAQ, Best Practices
```

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

### Download and Upload Embrace Support Tools

Source: https://embrace.io/docs/ios/best-practices/ci-dsym-upload

Shows how to download the Embrace support tools, including the symbol upload utility, using `curl` and `unzip`, and then execute the upload command.

```shell
curl -o ./embrace_support.zip https://downloads.embrace.io/embrace_support.zip
unzip ./embrace_support.zip
./embrace_symbol_upload.darwin -app $APP_KEY -token $API_TOKEN dsym_output.zip
```

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

### Get Current Device ID

Source: https://embrace.io/docs/ios/6x/getting-started/migration-guide

Similar to session ID retrieval, the method for obtaining the current device identifier has been changed from `getDeviceId()` to `currentDeviceId()`. This aligns with the SDK's trend towards more direct property access.

```APIDOC
currentDeviceId()
  Retrieves the unique identifier for the current device.
  Replaces: getDeviceId()
  Usage:
    let deviceId = Embrace.currentDeviceId()
    print("Device ID: \(deviceId)")
  Parameters:
    None
  Returns:
    String: The unique device identifier.
```

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

### Get Current Session ID (Objective-C)

Source: https://embrace.io/docs/ios/5x/features/current-session-id-api

Retrieves the current Embrace Session ID using the Objective-C SDK. Returns the session ID as an NSString or nil if no active session exists. Call after the SDK has started.

```Objective-C
NSString* sessionId = [[Embrace sharedInstance] getCurrentSessionId];
```

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

### Get Current Session ID (Swift)

Source: https://embrace.io/docs/ios/5x/features/current-session-id-api

Retrieves the current Embrace Session ID using the Swift SDK. Returns the session ID as a String or null if no active session exists. Call after the SDK has started.

```Swift
let sessionId = Embrace.sharedInstance().getCurrentSessionId();
```

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

### Embrace SDK Initialization with Custom Capture Services (iOS)

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

Demonstrates initializing the Embrace SDK in Swift, including custom capture services for network request ignoring. This example shows how to pass the configured `servicesBuilder` and an `OpenTelemetryExport` configuration during setup.

```Swift
try Embrace
    .setup(
        options: Embrace.Options(
          appId: "__YOUR APP ID__",
          platform: .reactNative,
          captureServices: servicesBuilder.build(),
          crashReporter: EmbraceCrashReporter(),
          export: OpenTelemetryExport(spanExporter: traceExporter, logExporter: logExporter) // passing the configuration into `export`
        )
    )
    .start()
```

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

### Batch Operations with Parent Spans

Source: https://embrace.io/docs/ios/6x/best-practices/performance-optimization

Illustrates how to handle operations that generate many log entries or spans by batching them. This example shows starting a single parent span for processing multiple items to reduce overhead.

```swift
// Instead of starting/ending many small spans
func processItems(items: [Item]) {
    // Start a parent span
    let parentSpan = Embrace.client.startSpan(name: "process_items_batch")

    for item in items {
        // Process each item
        processItem(item)
    }

    // End the parent span
    parentSpan.end()
}
```

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

### Initialize Embrace Web SDK

Source: https://embrace.io/docs/web/getting-started/basic-setup

Initializes the Embrace SDK with your application's unique app ID and version. This should be called as early as possible in your application's lifecycle to ensure comprehensive telemetry collection.

```javascript
import { sdk } from '@embrace-io/web-sdk';

const result = sdk.initSDK({
  appID: "YOUR_EMBRACE_APP_ID",
  appVersion: "YOUR_APP_VERSION",
});

if (!!result) {
  console.log("Successfully initialized the Embrace SDK");
} else {
  console.log("Failed to initialize the Embrace SDK");
}
```

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

### Embrace iOS SDK 5.x Command Line Tool

Source: https://embrace.io/docs/ios/5x/integration/next-steps

Details the command-line interface tool for the Embrace iOS SDK, likely used for tasks such as dSYM uploading or configuration.

```apidoc
APIDOC:
  CLI Tool:
    Description: Command Line Tool for the Embrace iOS SDK.
    Purpose: Facilitates specific tasks related to SDK integration and data management.
    Link: /docs/ios/5x/integration/cli-tool/
    Related: Uploading dSYMs, Integration Guide
```

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

### Create Manually Timed Span with recordCompletedSpan

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

This example illustrates how to use `recordCompletedSpan` to create a span with manually defined start and end times. It allows specifying error codes, parent spans, attributes, and events for detailed tracing of operations with known durations.

```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<boolean>;

// 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("span-name", startTime,
                            endTime, "None", undefined, attributes, events)
```

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

### Embrace SDK Android Startup Metrics Mapping

Source: https://embrace.io/docs/android/features/performance-instrumentation

Details how Embrace SDK's startup metrics align with standard Android startup performance measurements, including references to Android APIs and concepts like Time to Initial Display and Time to Full Display.

```APIDOC
Android Startup Metrics Mapping:

This section describes the correlation between Embrace SDK's startup metrics and native Android startup performance metrics.

Embrace Metrics vs. Android Metrics:

- emb-activity-init-delay: Time between Application object creation and first Activity initialization. Corresponds to the initial phase of app startup.
- emb-activity-init: Time from Activity initialization start to reaching the STARTED lifecycle stage. Maps to early Activity lifecycle events.
- emb-activity-render: Time between Activity initialization and first frame delivery. Recorded for Android 10, 11, 13+. Correlates with visual rendering milestones.
- emb-activity-first-draw: Time between Activity initialization and first draw detection. Recorded for Android 6-9, 12. Also relates to visual rendering.
- emb-activity-load: Time between Activity initialization and reaching the RESUMED lifecycle stage. Recorded for Android 5. Maps to the point where the Activity is interactive.
- emb-app-ready: Time between trace end and appReady() call. Recorded if startup traces end programmatically. Relates to custom application readiness signals.

Mapping to Android Startup Metrics:

- Time to Initial Display (TTID): Embrace's automatic trace end time is similar to TTID, but it waits for the first drawn frame delivery, whereas TTID often relies on rendering completion.
- Time to Full Display: To synchronize with this, developers can align `reportFullyDrawn()` calls with `appReady()` invocations, potentially using `FullyDrawnReporter`.

Related Android APIs and Concepts:

- Logcat: Source for Android app startup metrics.
- Perfetto: Performance tracing tool for Android.
- ApplicationStartInfo API (Android 15+): Provides application startup information.
- reportFullyDrawn(): Method to signal that the app has fully rendered.
- appReady(): Custom method to signal application readiness.
- FullyDrawnReporter: Utility for managing full draw reporting.
```

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

### Update Cocoapods for Embrace React Native

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

This command updates the EmbraceIO cocoapods and installs dependencies in your iOS project. It's a crucial step after updating the SDK packages to ensure native modules are correctly linked.

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

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

### Logging Examples

Source: https://embrace.io/docs/ios/6x/api-reference/embrace-client

Demonstrates various ways to log messages with the Embrace SDK, including basic logging, logging with severity and attributes, and logging with attachments.

```swift
// Basic logging
Embrace.client?.log("User logged in", severity: .info)

// Logging with attributes
Embrace.client?.log(
    "Network request failed",
    severity: .error,
    attributes: ["url": "https://api.example.com"]
)

// Logging with attachment
let jsonData = try JSONSerialization.data(withJSONObject: ["key": "value"])
Embrace.client?.log(
    "Debug data attached",
    severity: .debug,
    attachment: jsonData
)
```

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

### Get Current Session ID (Unity/C#)

Source: https://embrace.io/docs/unity/features/current-session-id-api

Retrieve the current Embrace Session ID using the SDK. This method returns null if called before the SDK has started or if Background Activity is disabled. It's recommended to call this after the SDK has initialized.

```csharp
Embrace.Instance.GetCurrentSessionId();
```
Tokens:
Raw