Skip to main content

jss configuration

This endpoint is used in implementations that use only Optimize. In this case, it is typical that the Sitecore CD instance sits behind a CDN.

Activating edge-side personalization#

In order for edge-side personalization instructions to be included in the Layout Service output, the request must indicate that these instructions should be included. Information on how this is enabled is included in the documentation that covers emitting instructions.

note

Activating edge-side personalization results in XML tags being injected in the Layout Service output. When this output is delivered by a CDN that supports edge-side personalization, these XML tags will be replaced with JSON.

However, attempting to use this output without a CDN to convert the XML tags will break your JSS application.

Format of the output#

When this endpoint is accessed through a properly-configured CDN, the output will be indistinguishable from the output of the endpoint when delivered by a Sitecore CD instance, but it will include any personalized content that is appropriate.

The response from the CDN, however, may include cookies. These cookies are used to maintain state required for personalization to work properly.

The output with the XML tags has a couple of hallmarks:

  • Edge Context - This is injected through a placeholder esi-context that is added to the route. See the documentation on Edge Context for more information.
  • Personalized renderings - Each rendering in the route that has personalization rules assign will be wrapped in XML tags. Those tags represent the conditional logic described in the personalization rules.

Troubleshooting output#

You can troubleshoot the output from this endpoint by activating edge-side personalization directly on your Sitecore CD instance. The easiest way to do this is to add the following to the url for the endpoint:

&uniform_esi=true

This will show you the XML tags that represent the logic that runs on the CDN. These tags are ESI (edge-side include) tags. The CDN is able to execute these ESI tags in order for execute dynamic functionality.

note

Your CDN does not need to support ESI in order for ESI tags to be executed. For example, when Cloudflare is used, a Cloudflare Worker is used to execute the ESI tags. Cloudflare does not support ESI natively, but it can still runs ESI tags.

ESI is a well-documented, standard technology. It is beyond the scope of this documentation to explain how it works. But the following tips should help you to troubleshoot Uniform-specific errors:

Edge Context#

The most complex ESI tags involved with edge-side personalization are the tags that create the Edge Context. The documentation that covers the Edge Context provides troubleshooting tips.

Broken ESI tags#

In order for the ESI tags to run, they must be well-formed. Confirm that the XML tags do not contain any special characters and tags are closed properly.

tip

A Docker image with a tool that allows you to test ESI tags is available from Akamai. You can use this tool even if you are not using Akamai as your CDN. This tool is not a perfect replication of the component that Uniform uses to execute ESI tags, but it can be very helpful when troubleshooting ESI tags, especially when broken tags are the problem.