HomeEngagementContentDiscoveryOther Resources

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:

  • **React** Please use the `HTTPS=true` environment variable. See [Using HTTPS in Development](🔗) for details.

  • **Angular** Please use the `--ssl` flag. See [ng serve](🔗) for details.

  • **Vue CLI** Please use the `--https` flag. See [vue-cli-service serve](🔗) for details.

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.

**Note:**

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.