Experience manager application SPA integration

📘

Note

This page describes how SPAs integrate with the Experience manager application. It is provided as background information. If you follow our best practices and use the SPA SDKs, this integration is provided out-of-the-box through the SDK.

Introduction

Integration of an SPA with the Experience manager application enables Site Editors to customize, add, move, and remove components of that SPA. Such manageable components are defined in the site configuration and Content SaaS exposes them through the Delivery API to the SPA, which must be aware of the concept of components, as well as of the specific set of components available to the SPA.

Conceptually, the integration between an SPA and the Experience manager application is bi-directional: if a Site Editor changes parts of the Page, the SPA must be notified, and if the visitor of the (preview) page, displayed in the Experience manager application, changes the state/route of the SPA, the Experience manager must be notified. In both scenarios, the goal is that the SPA and the Experience manager application stay in sync.

Communication between SPA and Experience manager

PostMessage-based Remote Procedure Call (RPC)

All the communication between an SPA and the Experience manager application relies on the postMessage API. The API provides an event-based communication between the SPA context and the Content SaaS context.

The API is based on the event model and all the two-way communication with the Experience manager application is fully asynchronous. When needed, the SPA sends a message with a unique identifier which Content SaaS will include in the response message. The message identifier will be used by the SPA to determine the result of the remote call. The communication works the same way in the opposite direction when the SPA responds to a request coming from Content SaaS.

Security concerns

The SPA SDK ensures that the event origin matches the Content SaaS environment base URL. On the other side, Content SaaS ensures the message origin matches the configured SPA URL.

The same concerns are taken into account to limit the recipients of outgoing messages.

Message types

The following three message types are used in the communication between an SPA and the Experience manager application:

• Events
  Messages of the event type do not require an acknowledgement or a result from the remote side and do not contain any identifying data in the payload.
• Requests
  Messages of the request type require a response from the remote end and represent remote procedures. On the other side those procedures always have a 1 to 1 connection with some code or a function. The message payload must contain a unique identifier so the caller can identify the response.
• Responses
  Messages of the response type contain a result or a thrown error of the remote call. The message should include an identifier received in the request.

Interaction diagrams

The following interaction diagrams depict the communication between browser, SPA and Content SaaS in the cases of an initial page rendering and a component update.

Initial rendering

The initial rendering flow is described in Image 1. The initialization consists of three steps:

1. Notify Content SaaS that the integration part is ready.
2. Inject the requested Content SaaS JavaScript asset.
3. Synchronize all the overlays after the rendering.

Image 1. Initial rendering

Component update

The component update flow is described in Image 2. The update consists of two steps:

1. Notify the SPA about the component update.
2. Synchronize all the overlays after the rendering.

Image 2. Component update

Reference