Salesforce LWC observability reference

This topic documents how to get started with the LaunchDarkly observability plugins in a Salesforce Lightning Web Components (LWC) application. Salesforce LWC applications run in the browser, so you can use the LaunchDarkly client-side JavaScript SDK and its observability plugins directly. With a few lines of code you can:

Capture and replay end-user sessions
Identify and reproduce bugs quickly
Monitor performance metrics
Gain insights into end-user behavior

The LaunchDarkly JavaScript SDK supports the following observability plugins:

An observability plugin for error monitoring, logging, and tracing.
A session replay plugin that provides a way to record and replay end-user sessions from your application.

This integration works with Salesforce LWC and requires minimal changes to your existing codebase. Because Salesforce controls the pages that host your components, the main setup work is adding the SDK to your site’s head markup and updating Salesforce’s content security policy (CSP) settings so the browser can load the SDK and send observability data to LaunchDarkly.

SDK quick linksLaunchDarkly SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:

Resource	Location
SDK API documentation	Observability plugin API docs Session replay API docs
GitHub repository	@launchdarkly/observability
Published module	npm

For use in client applications onlyThe session replay plugins are available only for the LaunchDarkly client-side JavaScript-based SDKs.To learn more about LaunchDarkly SDK types, read Choosing an SDK type.

Prerequisites and dependencies

This reference guide assumes that you are familiar with the LaunchDarkly JavaScript SDK and with Salesforce Experience Builder. The observability plugin requires JavaScript SDK version 3.7.0 or later. You need access to your Salesforce site’s Experience Builder settings, including the head markup editor and the security settings, to complete the steps in this guide.

Get started

Follow these steps to get started:

Configure the head markup
Configure the CSP settings
Configure trusted URLs
Explore supported features
Review observability data in LaunchDarkly

Configure the head markup

Because Salesforce Experience Cloud sites do not use a JavaScript bundler for site-level scripts, you must load the SDK and observability plugins using <script> tags in the site’s head markup. The scripts load once and persist as end users navigate your site. To add the SDK and plugins to your site, follow these steps in Salesforce Experience Builder:

Navigate to Setup > Digital Experiences > All Sites, then open the Builder for your site.
Navigate to Settings > Advanced in Builder, then click Edit Head Markup.
Add <script> tags that load the JavaScript SDK and the observability plugins.
Add another <script> tag that initializes the SDK client with the plugins.
Save the head markup.

Do not use script tags from unpkg or jsDelivr in productionDo not use script tags with sources from unpkg or jsDelivr in production environments. These introduce a critical dependency on a third-party service. Use the unpkg and jsDelivr scripts only during development for ease of use when getting started.In production environments, we strongly recommend that you self-host the JavaScript SDK and observability plugins alongside your other JavaScript resources, for example as Salesforce static resources or on a content delivery network (CDN) that you control. To learn more, read Make the SDK available with a script tag in the JavaScript SDK reference guide.

Here is an example of the head markup:

<script src="https://your-cdn.example.com/ldclient.min.js"></script>
<script src="https://your-cdn.example.com/ld-observability.min.js"></script>
<script src="https://your-cdn.example.com/ld-session-replay.min.js"></script>
<script>
  var client = LDClient.initialize('example-client-side-id', {
    plugins: [
      new LDObservability(),
      new LDSessionReplay()
    ]
  });
</script>

<script crossorigin="anonymous"
  src="https://cdn.jsdelivr.net/npm/@launchdarkly/js-client-sdk@EXAMPLE-VERSION">
</script>
<script crossorigin="anonymous"
  src="https://cdn.jsdelivr.net/npm/@launchdarkly/observability@EXAMPLE-VERSION">
</script>
<script crossorigin="anonymous"
  src="https://cdn.jsdelivr.net/npm/@launchdarkly/session-replay@EXAMPLE-VERSION">
</script>
<script>
  var client = LDClient.initialize('example-client-side-id', {
    plugins: [
      new LDObservability(),
      new LDSessionReplay()
    ]
  });
</script>

To initialize, you need your LaunchDarkly environment’s client-side ID. This authorizes your application to connect to a particular environment within LaunchDarkly. To learn more, read Initialize the client in the JavaScript SDK reference guide.

JavaScript observability SDK credentialsThe JavaScript observability SDK requires a client-side ID. Client-side IDs are specific to each project and environment. They are not secret, and you can include them in client-side code. Do not embed a server-side SDK key in a client-side application.You can find client-side IDs and project keys in Project settings, on the Environments list. To learn more about key types, read Keys and credentials.

You can configure options for the observability plugins when you initialize the SDK. The plugin constructors take an optional object with the configuration details.

Session replays are obscured by defaultBy default, session replays use the strict privacy setting, which obscures some data. Use none to turn off session replay obfuscation. This enables more detail on session replays, but may expose more of your customer data than your privacy or data retention policies allow. To learn more, read Configuration for session replay.

To learn more about plugin options, read Configuration for client-side observability and Configuration for session replay.

Configure the CSP settings

Salesforce enforces a CSP on Experience Cloud sites. You must relax the security level and add trusted sites to enable the browser to load the SDK scripts and send observability data to LaunchDarkly. To update the CSP settings for your site:

Navigate to Settings > Security and Privacy in Builder.
Set the Security Level to Relaxed CSP.
Under Trusted Sites for Scripts, click + Add Trusted Site and add the host that serves the SDK scripts. This is your own CDN if you self-host, or https://cdn.jsdelivr.net if you are loading the scripts from jsDelivr during development.

Configure trusted URLs

Next, add the LaunchDarkly service domains as trusted URLs to enable the SDK and observability plugins to connect to LaunchDarkly:

Navigate to Setup > Security > Trusted URLs.
Click New Trusted URL.
Add an entry for each of the following URLs, with the connect-src CSP directive enabled:

https://clientsdk.launchdarkly.com: This allows the SDK to fetch flag evaluations.
https://clientstream.launchdarkly.com: This allows the SDK to receive streaming flag updates.
https://events.launchdarkly.com: This allows the SDK to send analytics events.
https://pub.observability.app.launchdarkly.com: This allows the observability plugins to send recorded observability data.
- https://otel.observability.app.launchdarkly.com: This allows the observability plugins to send telemetry data.

Explore supported features

The observability plugin supports the following features. After the SDK and plugins are initialized, you can access these from within your application:

Review observability data in LaunchDarkly

After you initialize the SDK and observability plugins, your application automatically starts sending observability data back to LaunchDarkly in the form of custom events. You can review this information in the LaunchDarkly user interface. To learn how, read Observability. Specifically, the observability data includes events that LaunchDarkly uses to automatically create the following metrics:

Average, P95, and P99 Cumulative Layout Shift (CLS) per context (LaunchDarkly)
Average, P95, and P99 Document Load Latency per context (LaunchDarkly)
Percentage of users with errors (LaunchDarkly)
Average, P95, and P99 First Contentful Paint (FCP) per context (LaunchDarkly)
Average, P95, and P99 First Input Delay (FID) per context (LaunchDarkly)
Average, P95, and P99 Interaction to Next Paint (INP) per context (LaunchDarkly)
Average, P95, and P99 Largest Contentful Paint (LCP) (LaunchDarkly)
Average, P95, and P99 Time to First Byte (TTFB) per context (LaunchDarkly)

To learn more, read Metrics autogenerated from observability events.

​Prerequisites and dependencies

​Get started

​Configure the head markup

​Configure the CSP settings

​Configure trusted URLs

​Explore supported features

​Review observability data in LaunchDarkly

Prerequisites and dependencies

Get started

Configure the head markup

Configure the CSP settings

Configure trusted URLs

Explore supported features

Review observability data in LaunchDarkly