SiteSpect and Single-Page Applications

What is a Single-Page Application?

Single-Page Applications (SPAs) deliver an app-like experience on desktop and mobile browsers. In most cases, all of the application code is loaded on the initial request (first page load) and the content is changed dynamically without new page loads. You can control the application using JavaScript to send client-side requests for fresh data. Because the browser does not have to reload the entire page once the application code is loaded the first time, visitors benefit from an improved experience and speed.

How does SiteSpect support SPAs?

SiteSpect supports testing, personalization, and optimization of SPAs in multiple ways. Historically, SiteSpect has optimized SPAs using origin experiments, a powerful server-side testing capability in which SiteSpect signals the origin web server with a header, cookie, or URL. This approach is still available and applicable; in addition, SiteSpect offers its SPA SDK and Client-Side Variations that work with all dynamic content and allow you to quickly build tests.

How does SiteSpect interact with your SPA?

When interacting with your regular website, SiteSpect acts on every request.

When interacting with an SPA website, SiteSpect works on the initial request (signaling the origin with Origin Experiments on the request or injecting JavaScript based changes on the response) since navigating in the SPA does not make additional HTML requests. In the initial request, SiteSpect makes assignment decisions and injects Client-Side Variations, stored as a JavaScript variable that contain the changes you want to apply in your application, that are applied by the SPA SDK. Together, Client-Side Variations and the SPA SDK provide powerful testing capabilities for single-page applications.

Note: The SiteSpect SPA SDK supports only Internet Explorer (IE) 11 and later. It also works on IE 9 and IE 10 with a Mutation Observers Polyfill.

What is the SPA SDK? What files are required?

The SPA SDK is a very lightweight JavaScript library (less than 5kb gzipped) delivered in one file but composed of two smaller libraries:

SSDomVar – Library that uses Mutation Observers to identify when changes should be applied and logic to evaluate client-side Variations and Triggers and apply changes (ssdomvar.js).
EventTrack – Library that captures client-side events and sends data to SiteSpect to populate Metrics (core.js).

GenericAdapter – While not required, this library is often added to leverage Mutation Observers with custom JavaScript code (generic-adapter.js).
The SPA SDK evaluates and applies Client-Side Variations using Mutation Observers.

Note: You can use the generic-adapter.js for JavaScript in regular Factors that use Mutation Observers to trigger the change. The static container for Mutation Observers is the HTML tag.

Note: To concatenates files, use a plus sign in your script source. Example: /__ssobj/core.js+ssdomvar.js+generic-adapter.js

How do I set up the SPA SDK?

To set up the SPA SDK:

Create an SPA Site Variation or Campaign Variation and use the SPA button to inject template code.
In the A/B Campaign Builder, select Client-Side from the Type drop-down. On the Variations tab, create a Client-Side Variation by specifying what information to change and where to change it. You can also build Client-Side Variations in the Visual Editor.
Run the Campaign. The SPA SDK applies the changes defined by your Client-Side Variation.

Note: If you have questions while setting up the SPA SDK, contact the SiteSpect Help desk ( +1-844-859-1900 or helpdesk@sitespect.com).

Creating and Previewing a Client-Side Variation

A Client-Side Variation is a data layer that is injected onto the page by the SiteSpect Engines. By itself, the data layer doesn’t do anything. You must inject the SPA SDK onto the page as well (with a Site or Campaign Variation) which will apply the changes on the page defined in the Client-Side Variation.

To create a Client-Side Variation, follow the instructions provided in Defining a Client-Side Factor.

To preview the change described by a Client-Side Variation on one of your pages, you must inject the SPA SDK onto the page as well. The SPA SDK applies the change described by the Client-Side Variation and indicates when to apply the change given the SPA framework. Use a Site Variation or Campaign Variation to inject the SPA SDK.

SiteSpect injects the Client-Side Variation right after the body tag. You can configure where the Client-Side Variation is injected in Site Settings. See Injecting the Client-Side Variation. The following is an example:

In the above example, variations is an array of Variations assigned by the Client-Side Factor. In addition, timestamps is the time the Variation (keyed by id) was modified.

Injecting the Client-Side Variation

SiteSpect injects the Client-Side Variation onto the page right after the body tag by default. However you can change the location where the Client-Side Variation is injected as follows:

Select Site, Configuration, Site Settings.
Select the Features tab.
Scroll down the page to the Client-Side Injection fields.

The defaults are as follows:

Find: (\A.*?</head>\s*<body[^>]*>)

Replace: '$1\n__SS_CSDATA__';

You can customize these fields, depending on where you want to inject the Client-Side Variations on the page. Contact the SiteSpect Help Desk at helpdesk@sitespect.com or +1-844-859-1900 for more information.

Triggers for Client-Side Factors

Client-Side Factors support both regular Triggers (that define when code should be injected onto the page) and Client-Side Triggers (that define when the changes should be applied on the page). Typically, for a single-page application, you want to inject Client-Side Factors everywhere and not use normal Triggers. However, if only a portion of your website is an SPA, you may want to limit the injection to specific pages.

When we talk about injecting and applying, we are using the following definitions:

Injecting: SiteSpect Engine puts the changes into the source code of the page.
Applying: SiteSpect SPA SDK processes and executes the changes.

Analytics and Integrations

SiteSpect’s Web Analytics Tag Transformation and Segmentation (WATTS™) feature allows you to dynamically insert tracking information about website visitors into tracking tags used by all major web analytics programs. The tracking information includes data on various SiteSpect components including Visits, Campaigns, viewed Variations, and more. Using WATTS, you can view, segment, and analyze SiteSpect Campaign data within a third-party web analytics program.

Counted State and WATTS

By default, the SiteSpect SPA SDK pings SiteSpect asynchronously (using /__ssobj/asmt_update) when a change is applied to update assignment data. This ping also updates the counted state for a visit if the Client-Side Factor is set to Count User when Triggered. By default, the ping returns an empty body and a 204, but it can be used to return updated assignment and WATTS variables.

To configure this call, you can define the WATTS macros in a JSON structure for the AJAX response as follows:

Select Site, Configuration, Site Settings.
Select the Features tab.
Scroll down until you see Client-Side WATTS Template. Use this text area to define your WATTS macros.

A callback function is called with the data in the response so that a data layer on the page can be updated with an updated assignment. The callback function name is defined via ss_dom_var.setAsmtCallback; we recommend that you define this function in the WATTS Site Variation.

Example:

If the callback function is not defined, the data from the response can be accessed from SS.getAsmtData().

Simple SPA Example

A visitor opens a browser and makes a request to a domain that returns a web application built with Angular. When the request flows through the SiteSpect reverse proxy, the HTML page is automatically injected with SPA SDK that hooks into the Angular framework. If the visitor is assigned to a Campaign with Client-Side Variations, these Variations are also injected into the page, ready to be used by the SiteSpect SPA SDK. As the visitor navigates through the web app, the SPA SDK applies changes from the Client-Side Variations to the page. When the Campaign ends, any request to the origin no longer injects the Client-Side Variations and the default experience resumes.