HomeEngagementContentDiscoveryOther Resources
Guides

SPA integration troubleshooting

Suggest Edits

This page provides information about common problems that you may run into while integrating Single-Page Applications (SPAs) with Bloomreach Content. Each section consists of a problem explanation, potential reasons causing the problem, and the solution that may help to solve the problem.

We'll continually update this page as we receive more feedback.

Channel preview in the Experience manager works intermittently in a clustered environment

Reason

The most likely cause for this issue is the session affinity between subsequent calls to CMS cluster nodes. The session affinity relies on a server-id query parameter being passed from Bloomreach Content during the redirect to the SPA. The SPA SDK will retrieve the received parameter and pass it to subsequent requests as a Server-id header. Bloomreach Content will pick this header and forward the incoming request to the appropriate cluster node.

If the SPA omits the received server-id parameter, the SPA SDK will not add a Server-id header in the outbound request to the Delivery API and the request will be dispatched in a round-robin fashion. As a result:

  • Calls that hit the cluster node aware of the user's session will succeed with a status 200 and the SPA loading fine in the Experience manager.
  • Calls that hit a cluster node that doesn't hold the user's session will fail with a status 401 or 500, the SPA will fail to get a response from the Delivery API. 

Solution

Always include the full requested path with all its parameters in the property request.path of the configuration object that gets passed to the SDK.

"Mixed content" issues and/or warnings in the Experience manager

Your SPA channel in not displayed in the Experience manager and/or your browser is displaying "mixed content" warnings when viewing an SPA channel in the Experience manager. Your Bloomreach Content environment uses HTTPS but your SPA uses HTTP.

Reason

Modern browsers typically block the display of a page or display warning messages if secure content (HTTPS) is mixed with insecure content (HTTP).

This can occur in your development environment when, for example, loading an SPA channel in the Experience manager while Bloomreach Content uses HTTPS and the SPA uses HTTP.

Solution

To avoid mixed content issues while developing your SPA, make sure your SPA uses HTTPS.

HTTPS can be enabled in most frontend frameworks through a single configuration variable, see below for some popular frameworks:

Although it is also possible to enable mixed content in most browsers, this workaround is not recommended.

If, after associating a local SPA using HTTPS with a development project, the Experience manager channel preview still doesn't load or shows an error, you may need to open the SPA in a separate browser tab and explicitly ignore the warning that the connection is not private and may be unsafe. Since you are in full control of the application, it is safe to ignore the warning.

❗️

Important

Production instances should always use HTTPS!

Previous versions of a page are not loading in the channel preview when selected in the page's version history in the Experience manager.

Reason

When selecting a specific version from a page's version history in the Experience manager, a version identifier is passed to the frontend application in a request parameter called br_version_uuid. The frontend application must pass the br_version_uuid request parameter on to the Delivery API's Pages endpoint so that the correct version of the page is returned. The SPA SDK implements this out of the box.

If you experience this issue, most likely you are using a custom frontend integration (i.e. not using the SPA SDK) and you are not passing on the br_version_uuid request parameter to the Delivery API. In absence of the version identifier, the Delivery API returns the latest version of the page.

The easiest way to confirm this is the case is by monitoring requests to the frontend application and to the Delivery API while selecting page versions in the Experience manager.

Solution

In your custom frontend integration, always check requests for the presence of the request parameter br_version_uuid and, if present, pass it on in the subsequent request to the Delivery API's Pages endpoint.

My Web Application Firewall (WAF) blocks requests to the channel preview in the Experience manager because they trigger the Owasp-crs-v030301-id931110-rfi (remote file inclusion) rule.

Reason

The remote file inclusion (RFI) security rule is triggered by the preview iframe of the Experience manager loading the SPA with an endpoint query parameter containing a full URI, as in the following example:

https://brx-reference-spa-latest.netlify.app/?token=[...]&server-id=[...]&endpoint=https://mycontent.bloomreach.io/delivery/site/v1/channels/mychannel/pages

Because the value of the parameter is a fully qualified URL, it is considered a remote file inclusion (RFI) vulnerability.

The endpoint query parameter is required for Bloomreach-hosted multi-tenant SPAs that are used as default frontend for newly created channels. A new channel's remoteHostProtection property is set to false by default. When opening a channel with remoteHostProtection set to false in the Experience manager, the endpoint query parameter is added to the SPA URL. The SPA SDK will use the URL specified in the 'endpoint' query parameter only if the SPA does not have the endpoint set through an environment variable.

Typically the endpoint query parameter becomes redundant once a customer deploys their own SPA that uses an environment variable to specify the endpoint.

Solution

The solution is to deploy your own SPA application, specifying the endpoint in an environment variable, and to enable remoteHostProtection for each of your channels using the Site Management API's channel endpoint.

If you don't have your own SPA yet, you can start with cloning the Reference SPA github project. Make sure to set NEXT_PUBLIC_BRXM_ENDPOINT in .env to the appropriate Delivery API endpoint for your environment and channel as explained in the README.

Use the Site development app or the Site Management API's channels endpoint directly to set the remoteHostProtection property for your channel(s) to true.

The Experience manager shows the live channel instead of the channel preview or does not update the preview when editing a component

Reason

The most likely cause is the token header missing from Delivery API requests sent by the SPA.

For the Experience manager to render the channel preview correctly, Delivery API requests from the SPA must include the token and server-id headers which are stored in the client configuration object.

The SDK handles this transparently by default but in case of SPA implementations that use the SDK selectively or in a non-standard way, developers may need to take care of the headers explicitly.

Solution

Make sure your SPA always includes the token and server-id headers in requests to the Delivery API.

If you are using the SPA SDK selectively on certain pages, you will need to persist the preview related data when navigating between pages that have and those that don't have a SDK instance. See Persist preview data for pages without SDK instance in the SDK documentation for details.

The Experience manager shows an incorrect project name

The project name displayed in the project selector does not match the project displayed in the channel preview.

Reason

The most likely reason is that the channel preview requests by the Experience manager are being cached by the SPA.

When the user switches to a different project, the selected project is updated in the server's session context, and the Experience manager reloads the page, expecting the reloaded page to be driven by a project-specific Delivery API response. However, due to the caching in place, the page reload never hits the server, and the selected project is not reflected correctly on the previewed page.

Solution

Ensure your SPA does not cache any pages in a preview context in the Experience manager. Preview page requests always include a token request parameter, for example:

https://example-spa.example.com/?token=eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI5MzBlYzY3NC01NzgyLTQ1MDEtYThmMS02M2VhYmJmOTdhMmQifQ.WTB0636SnSKPbZO0ldUTc8arjFkWj1piU0tVXpGptzhNmwzizX_16YGBW1SvmP4xP34x18v4jBJuOeppsZuGO2RbyhgXKfZ2-_HKl9r7XLNW-FRrUYLijUbY1I2t-wUjnSGzm2hhGoHOk4CP9KrsQEJXKlZ4ijX3wjwXTOsfVZOguhKPGr45n2XUEy5CYor7YDkN_2YCmjoXn3BKyOnkeGlZC_uVJvo0jReB299ICxWth5fOFeNZYcA55CtT66i8H-GIHUHrVoZDikhRcQfkjkgO4NbRanx9Oj1Z3hP025RPycewaXxglSRBSu8FCYYlw6mMF1Tk--k2PndyZg3YvQ&server-id=cms-green-techdoc-development-gloo-one-7958d4588d-7tptn&endpoint=https://example-account.bloomreach.io/delivery/site/v1/channels/example-channel/pages

These requests should never be cached at the SPA level.

In addition, ensure that preview responses don't include any headers triggering the browser to cache those responses.

Channel toolbar is not initialized

Inside the Experience manager, the channel toolbar is not appearing (see screenshot below), but the SPA is fully functioning.

Channel toolbar is not initialized.

Channel toolbar is not initialized.

Reason

  • The SPA is loading components asynchronously but doesn't call the .sync() function after the page has loaded.
  • The Delivery API request in the Experience manager is missing the following headers: Authorization and Referer.

Solution

Updated about 1 month ago