Embed Your React App in Lightning Experience or Experience Cloud

Learning Objectives

After completing this unit, you’ll be able to:

Identify where you can embed a Multi-Framework app that Salesforce hosts.
Configure Trusted URLs for a Lightning Experience page.
Configure the extra session and cookie settings that an Experience Cloud site requires.
Create a wrapper Lightning web component that embeds your app.
Add your wrapper component to a page in Lightning App Builder or Experience Builder.

One App, Two Places to Put It

In the previous unit, you learned how UI Embedding renders an app inside a Salesforce page. Now you decide where your users see your app.

Lightning Experience: An app page, record page, or Home page that internal users open in Salesforce.
Experience Cloud site: A page in an LWR (Lightning Web Runtime) site or an Aura site.

You embed the app the same way in both places, with the wrapper component that renders lightning-ui-embedding and points it at your app. The difference is the trust configuration that you set up beforehand.

Confirm Your App Runs on Its Own

Before you embed your app, make sure that it loads by itself.

From the App Launcher, find and open your app.
Copy the app URL from the browser address bar after it loads. You use this URL when you create your wrapper component.

If the app doesn’t load, from Setup, in the Quick Find box, search for and select My Domain. Enable Salesforce Edge Network, and then try again.

Prepare Your App for Embedding

Before your app can load inside a Salesforce page, it needs one import. At the top of your app’s entry point, the file that runs first when your app starts, import the UI Embedding module.

import "@salesforce/platform-sdk/ui-embedding";

This import doesn’t give you anything to call. Instead, it runs setup code that connects your app to the host page, so the import must run before the rest of your code. After you add the import, deploy your app again.

Configure Trust Settings

Your app loads in an iframe from the Salesforce app domain, which is different from the page domain, so you tell Salesforce to trust *.salesforce.app. The specific trust settings depend on whether you embed the app in a Lightning Experience page or in an Experience Cloud site page.

Lightning Experience

Add a Trusted URL so that your org’s Content Security Policy (CSP) allows the app domain in an iframe.

From Setup, in the Quick Find box, search for and select Trusted URLs.
Add the Salesforce app domain (*.salesforce.app) with the frame-src CSP directive.

Experience Cloud Site

An Experience Cloud site establishes the app’s session through a chain of Salesforce domains inside the iframe, so it needs more settings than a Lightning Experience page.

From Setup, in the Quick Find box, search for and select Trusted URLs. Add these three URLs, each with the frame-src directive.
- The Salesforce app domain (*.salesforce.app)
- Your org’s Lightning domain (for example, *.lightning.force.com)
- Your My Domain URL (for example, *.my.salesforce.com)
In the Quick Find box, search for and select Session Settings. Under Trusted Domains for Inline Frames, add your Experience Cloud site URL and set the IFrame Type to UIEmbedding.
In the Quick Find box, search for and select My Domain. Under Routing and Policies, deselect Require first-party use of Salesforce cookies. The app relies on Salesforce cookies to establish its session inside the iframe, and this setting blocks those cookies in a framed context.

Create the Wrapper Component

The wrapper is a Lightning web component in your Salesforce DX project. You can write it yourself or generate it with Salesforce CLI.

To write the wrapper yourself, create a Lightning web component and add lightning-ui-embedding to its template. Set the required src attribute to the app URL that you copied earlier. Add a title too, which gives the iframe an accessible name.

Create these two files in your component folder.

<!-- propertyApp.html -->
<template>
  <lightning-ui-embedding
    src={appUrl}
    title="Property management app"
  ></lightning-ui-embedding>
</template>

// propertyApp.js
import { LightningElement } from "lwc";
export default class PropertyApp extends LightningElement {
  appUrl = "YOUR_APP_URL"; // The URL that you copied from the address bar
}

Alternatively, to generate the wrapper, run this Salesforce CLI command. Replace YOUR_APP_URL with the URL that you copied from the address bar. The command creates the component’s HTML, JavaScript, CSS, and metadata files. If the command isn’t available, update Salesforce CLI.

sf template generate ui-embedding --name propertyApp --src YOUR_APP_URL

Configure and Add the Wrapper Component to a Page

To use the wrapper in Lightning App Builder or Experience Builder, expose it and add a target for each place that you want to use it. In the wrapper’s .js-meta.xml configuration file, inside <LightningComponentBundle>, set isExposed to true and add your targets.

The lightning__ targets are for Lightning Experience pages, and lightningCommunity__Page is for Experience Cloud sites. Include only the targets for the places where you plan to use the wrapper.

<isExposed>true</isExposed>
<targets>
  <target>lightning__RecordPage</target>
  <target>lightning__AppPage</target>
  <target>lightning__HomePage</target>
  <target>lightningCommunity__Page</target>
</targets>

Then deploy the wrapper component to your org and add it to a page.

Lightning Experience: Open the page in Lightning App Builder, add your custom component onto the page, and then save and activate.
Experience Cloud: Open your site in Experience Builder, add your custom component onto the page, and then publish.

If your app doesn’t appear, open your browser’s developer console. A CSP error that mentions frame-src means that the page doesn’t trust your app’s domain. Check that each Trusted URL exists, is spelled correctly, and has the frame-src directive. If there’s no CSP error, check that your app imports @salesforce/platform-sdk/ui-embedding at its entry point.

To detect embedding problems in code, listen for the sf-embedding.component.error event on lightning-ui-embedding. For the list of error codes, see UI Embedding Error Codes.

With these steps, your app renders inside Salesforce, right where your users work. Next, make the embedded app work with the page by matching the page’s styling and warning users about unsaved changes.

예상 시간

주제

도움말 검색

Headless 360 Platform 자원