> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeycomb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the Embrace Integration

> Configure the Honeycomb and Embrace integration to forward mobile and web network spans to Honeycomb.

## Overview

The Embrace SDK forwards network spans directly to Honeycomb using an OTLP exporter, giving you mobile and web client telemetry alongside your backend traces.
Configuring metrics forwarding adds session-level data, including Application Not Responding (ANR) rates, crash rates, and Core Web Vitals.

## Before you begin

Before starting, confirm that you have:

* A Honeycomb environment with at least one backend service sending OpenTelemetry traces
* An Embrace account on an Enterprise plan
* A mobile or web app on a platform for which Embrace supports [Network Spans Forwarding](https://embrace.io/docs/data-forwarding/network-spans-forwarding/#sdk-version-requirements)

## Install and initialize the Embrace SDK

The Embrace SDK instruments your app and captures session data and network requests automatically once initialized.

<Steps titleSize="h3">
  <Step title="Install the Embrace SDK">
    The Embrace Web SDK is the package that provides the `EmbraceWebSDK` class you will use to initialize and configure the integration.

    <Tabs>
      <Tab title="npm">
        ```bash theme={}
        npm install @embrace-io/web-sdk
        ```
      </Tab>

      <Tab title="yarn">
        ```bash theme={}
        yarn add @embrace-io/web-sdk
        ```
      </Tab>
    </Tabs>

    For Android, iOS, React Native, and Flutter, visit [Embrace's SDK installation documentation](https://embrace.io/docs/).
  </Step>

  <Step title="Initialize the Embrace SDK">
    Initialize the SDK with your Embrace App ID and version:

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

    const embrace = new EmbraceWebSDK({
    appId: "YOUR_EMBRACE_APP_ID",
    appVersion: "YOUR_APP_VERSION",
    });

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

    <Tip>
      Your Embrace App ID and version are available in the Embrace dashboard.
    </Tip>

    Once initialized, the SDK begins capturing session data and network requests automatically.
  </Step>
</Steps>

## Set up network spans forwarding

Network spans forwarding stitches Embrace client spans into your backend traces in Honeycomb and enables the `emb.dashboard_session` deep link that connects a Honeycomb trace to the originating Embrace session.

<Steps titleSize="h3">
  <Step title="Configure domains for network spans forwarding">
    Network spans forwarding requires you to specify which apps and domains to forward spans from.
    Configure this in the Embrace dashboard:

    1. Navigate to **Settings** > **Integrations**.
    2. Select the **Network Spans Forwarding** view.
    3. Select **Honeycomb** as the data destination.
    4. Select the apps you want to forward spans from.
    5. Add the domain names of the backend services you want to trace.

    Embrace forwards spans only for configured domains, which must be internet-reachable.
    You can add domains as exact matches or use regex patterns for more flexible matching.
  </Step>

  <Step title="Create a Honeycomb Ingest Key">
    The Embrace SDK uses a Honeycomb Ingest Key to forward spans to your environment.
    If you already have an Ingest Key for this environment, you can use it here.

    To learn how to create a new Ingest Key, visit [Manage Environment API Keys](/configure/environments/manage-api-keys).
    When creating the key, enable **Create datasets**, so that Embrace can create a dataset for the forwarded spans.

    You will use this key in the next step to configure the SDK exporter.
  </Step>

  <Step title="Configure the Embrace SDK exporter">
    The exporter tells the Embrace SDK where to send spans.
    Add a Honeycomb OTLP exporter to your Embrace SDK configuration, using your Ingest Key as the `x-honeycomb-team` header:

    ```javascript highlight={6-10} theme={}
    import { EmbraceWebSDK } from '@embrace-io/web-sdk';

    const embrace = new EmbraceWebSDK({
    appId: "YOUR_EMBRACE_APP_ID",
    appVersion: "YOUR_APP_VERSION",
    exporters: [{
        type: 'otlp',
        endpoint: 'https://api.honeycomb.io/v1/traces',
        headers: { 'x-honeycomb-team': YOUR_HONEYCOMB_INGEST_KEY }
    }]
    });

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

    The SDK automatically attaches a W3C `traceparent` header to every network request your app makes and forwards the resulting spans to Honeycomb with `emb.*` attributes included.
  </Step>
</Steps>

## Set up metrics forwarding

Metrics forwarding sends session data from Embrace to Honeycomb, so you can query and alert on user experience signals alongside your backend traces.

<Steps titleSize="h3">
  <Step title="Create a Honeycomb Configuration Key">
    Embrace uses a Honeycomb Configuration Key to authenticate when forwarding metrics to your environment.
    To learn how to create one, visit [Manage Environment API Keys](/configure/environments/manage-api-keys).
  </Step>

  <Step title="Add Honeycomb as a Data Destination in Embrace">
    Adding Honeycomb as a Data Destination tells Embrace where to send session metrics.
    In the Embrace dashboard:

    1. Navigate to **Settings** > **Integrations**.
    2. Select the **Data Destinations** view.
    3. Select **Add Data Destination**.
    4. Choose **Honeycomb** and enter your Honeycomb Configuration Key.

    Once configured, Embrace forwards metrics to Honeycomb where you can query them alongside your trace data.
    To learn which metrics are forwarded, visit [Embrace Integration Overview: Session Metrics](/integrations/embrace/overview#session-metrics).
  </Step>
</Steps>

## Verify the integration

Verification confirms that both flows are working: spans appearing in the trace view means the SDK exporter is forwarding correctly, and metrics appearing in Honeycomb means the Data Destinations configuration is correct.

### Network spans

Spans appear in Honeycomb after the SDK exporter is configured and app traffic flows through a configured domain.

1. In Honeycomb, open the dataset that corresponds to your backend service.
2. Run a query and filter for `emb.app_id` exists.
3. Select a result row and open the trace view.
4. Confirm that the trace includes a span labeled **forwarded via Embrace** at the top of the waterfall, with `emb.*` attributes visible in the span detail panel.
5. Confirm that `emb.dashboard_session` appears as a clickable link in the span detail panel.

If you don't see spans after 15 minutes, refer to the [troubleshooting section](https://embrace.io/docs/data-forwarding/network-spans-forwarding/#troubleshooting) in Embrace's Network Spans Forwarding documentation.

### Metrics

Metrics should appear in Honeycomb within a few minutes of adding it as a Data Destination.

1. In Honeycomb, open the dataset that corresponds to your Embrace metrics.
2. Run a query and filter for `session.count` exists.
3. Confirm that data is appearing.

## Next steps

Now that your integration is configured, put it to work:

* [Investigate backend latency](/integrations/embrace/use-cases/investigate-backend-latency)
* [Diagnose mobile ANRs and hangs](/integrations/embrace/use-cases/diagnose-mobile-anrs)
* [Investigate with Embrace and Honeycomb MCP](/integrations/embrace/use-cases/investigate-with-mcp)