Migrate from the Developer Preview API
UI Embedding was first released as a Developer Preview. The generally available version changes the host element, how you pass the app URL, and how the host communicates with the embedded app. If you built an embedding against the Developer Preview, use this guide to move to the generally available component.
The Developer Preview and generally available APIs aren’t compatible. An app built for one doesn’t run under the other without the changes described here.
| Area | Developer Preview | Generally Available |
|---|---|---|
| Host element | <lwc-shell> | <lightning-ui-embedding> |
| App URL | Set through the shell’s configuration | src attribute (required, read once at mount) |
| Host-to-app communication | Imperative bridge object | DOM events on the host element and the sf-embedding protocol channel |
| Lifecycle signals | bridge callbacks | sf-embedding.component.ready and sf-embedding.component.error DOM events |
Replace the Developer Preview host element with lightning-ui-embedding, and move the app URL to the src attribute.
Before (Developer Preview):
After (generally available):
The src attribute is required and binds the session to a specific app. Salesforce reads it once when the component mounts. Don’t change src, sandbox, or removeSandboxTokens after the component renders. The host rejects a mid-session change with a SESSION_BINDING_MUTATED error.
The Developer Preview exposed an imperative bridge object for communication. The generally available version uses DOM events on the host element for lifecycle signals.
Listen for these events on lightning-ui-embedding:
sf-embedding.component.readyfires when the embedded app finishes the handshake and is ready.sf-embedding.component.errorfires when embedding fails. The event detail includes thephase(configurationorbootstrap), acode, amessage, and aretryableflag. See UI Embedding Error Codes.
These event names contain dots, so you can’t bind them declaratively with on* attributes in the template. Add lwc:ref to the embedding element and attach the listeners imperatively in renderedCallback.
In the generally available version, the page and the embedded app exchange state through the embedding’s typed channel rather than the Developer Preview bridge. Review these tasks for the current approach:
- Style an Embedded App to Match Salesforce
- Resize an Embedded App to Fit Its Content
- Track Unsaved Changes in an Embedded App
- Get Started with UI Embedding for the full generally available setup path.
- UI Embedding Error Codes to handle failures in your event listeners.