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.
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.
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.
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.
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.
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:
Please use the
HTTPS=trueenvironment variable. See Using HTTPS in Development for details.
Please use the
--sslflag. See ng serve for details.
- Vue CLI
Please use the
--httpsflag. 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.
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.
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.
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.
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:
Because the value of the parameter is a fully qualified URL, it is considered a remote file inclusion (RFI) vulnerability.
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.
endpoint query parameter becomes redundant once a customer deploys their own SPA that uses an environment variable to specify the endpoint.
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
.env to the appropriate Delivery API endpoint for your environment and channel as explained in the README.
Updated 17 days ago