Edge Context

Edge Context is a collection of edge-compute instructions that create variables that control personalization. When the instructions run, there is no output. The result is that variables are made available to the personalization engine.

note

Edge Context is also called ESI Context. ESI is the name of the technology used to implement the edge-compute instructions that generate Edge Context.

Understanding Edge Context#

Why is it needed?#

Edge Context solves a specific problem in the side personalization engine: the syntax for describing a personalization condition is very limited. Basically the syntax is limit to comparing one value to another. Some examples of comparisons that are supported are:

name equals "George"
age is greater than 18
city starts with "San"

But there are cases where more complex logic is needed. For example, what if you want to personalize on a cookie with the following value:

{   "name": "Elaine",  "age": 40,  "city": "Georgetown"}

The syntax for describing personalization would not allow you to properly describe the required comparison. There is no variable "name". The "name" value is a part of a JSON string. The logic for determining the value of "name" is much too complex for the edge-side personalization engine.

This is where Edge Context helps. Edge Context gives you a place to describe the rules for converting this complex value into simpler values that can be within the constraints of the the edge-side personalization engine.

How is it used during the personalization process?#

The Edge Context is generated before the personalization rules run. Most of the edge-side personalization conditions implement logic that compares values from the Edge Context to values the content author configured in Sitecore.

How is it created?#

Uniform adds a Sitecore pipeline named getEsiContext. This pipeline is responsible for generating the edge-compute instructions populate Edge Context.

Edge Context comes pre-configured with support for data that is collected by the Uniform tracker. This includes:

Campaigns that were triggered
Goals goals that were triggered
Personalization tests that are active
Profile scores that were collected
Personalization rules that were triggered

Adding Edge Context to a site#

When personalization runs on Sitecore, you can connect your Visual Studio debugger to the Sitecore process and see the values that are used in personalization. When personalization runs on the CDN, you cannot do this. Uniform provides a way to display the values in the Edge Context at runtime.

Edge Context is generated when page content is resolved. Since the page content resolution process depends on the type of site being rendered, the way Edge Context is added to a site depends on the type of site.

MVC#

For MVC sites, Edge Context must be added to the view that is responsible for the page layout. This is usually the same view that the Uniform tracker is added to.

Edge Context is added using an HTML helper method:

@Html.Uniform().Context()

note

Edge Context must be added to the view before any personalization is displayed. Because the Edge Context is rendered in a <script> tag, the best place to add this code is usually just inside the <head> tag.

JSS (React)#

For Sitecore JSS sites built with React, Edge Context is included in the Layout Service automatically. No additional steps are required.

Edge Context must be generated before any personalization runs. In order to ensure Edge Context is positioned accordingly in the Layout Service, Edge Context is rendered as a placeholder. Edge Context is the first placeholder rendered.

JSS (Next.js)#

For Sitecore JSS sites built with Next.js, Edge Context is included in the Layout Service automatically. No additional steps are required.

Extending Edge Context#

Developers can extend Edge Context to expose custom variables to the edge-side personalization engine. This is a critical feature in order to support custom Sitecore rule conditions.

The general process is:

Create a new processor for the pipeline getEsiContext.
Register the new processor on the Sitecore instance using a config file.

Examples are available in the section Custom Conditions.

Troubleshooting Edge Context#

Since Edge Context is a collection of edge-compute instructions that create variables for the edge-side personalization engine, there is no output that is visible on the page. Troubleshooting Edge Context requires being able to see the variables that make up Edge Context. This is supported through "Edge Context debug mode".

MVC#

Edge Context debug mode is incorporated into the HTML helper function used to add the Uniform tracker to an MVC view:

@Html.Uniform().TrackerWith(settings => {    settings.EnableContextDebug = true;})

This will result in a new script block being added to the page. The following is an example of the script block:

<script type="application/json" id="__ESI_CONTEXT__">{    "enabled": true,    "debug": true,    "variables": {        "ESI_CONTEXT_campaigns": "",        "ESI_CONTEXT_goals": "",        "ESI_CONTEXT_testing": "",        "ESI_CONTEXT_cookies_testing": "",        "ESI_CONTEXT_profiles_scores": "",        "ESI_CONTEXT_personalization_rules": ""    }}</script>

JSS (React)#

The following steps describe how to enable Edge Context debugging for a JSS site built using React.

In a Sitecore config file, add the following setting:

<setting name="Uniform.Optimize.Esi.Jss.Context.Debug" value="true" />

In the JavaScript console, you can enter the following command to see the ESI context values:

JSON.parse(window.__JSS_STATE__.textContent).sitecore.route.placeholders['esi-context'][0].fields

JSS (Next.js)#

The following steps describe how to enable Edge Context debugging for a JSS site built using Next.js.

In a Sitecore config file, add the following setting:

<setting name="Uniform.Optimize.Esi.Jss.Context.Debug" value="true" />

In the JavaScript console, you can enter the following command to see the ESI context values:

window.__NEXT_DATA__.props.pageProps.layoutData.sitecore.route.placeholders['esi-context'][0].fields