Introduction

Single-Page Application websites (SPAs) have become popular because of their ability to provide a more fluent user experience to visitors. It was made technically possible with the adoption of HTML 5, available out-of-the-box in Internet Explorer 10 and newer web browsers, and outstanding JavaScript frameworks (such as Angular, React, Ember, etc.)

Unlike traditional websites, SPA websites load content and resources dynamically. When a user interacts with the page, communication with the backend takes place behind the scenes without a new page generation and load cycle.

Prerequisites

Before you use the API, you need to:

Have SPA campaigns enabled for your website
Update your CD API version to 1.17 or newer

Challenge: Oracle Maxymiser and testing single-page websites

Oracle Maxymiser is implemented on test pages by loading an HTML JavaScript tag in the <head> section of the page. The browser calls our JavaScript library during the page load event, so campaign content is delivered and applied automatically even before the actual page content is displayed.

Since content on an SPA framework is primarily loaded without new page loads we cannot rely only on the initial page load from the server to run our test campaigns.

What's in the API?

With Campaign Design API version 1.17 we introduce SPA module to help marketers and developers design and build test campaigns on single-page websites. It uses the HTML5 pushState event ad DOM MutationObserver to allow applying changes on SPA websites based on custom rules, such as location change, specific node appearance, etc.

The module has been tested and used on Angular, React and other SPAs on the following browsers:

Internet Explorer 11
Safari latest
Chrome latest
Firefox latest
Edge latest

For the full list of SPA methods in the API, see SPA reference page.

Developing your SPA campaign

This article guides you through how to deploy your first SPA campaign in Maxymiser Campaign Designer using the API.

The difference between a standard and single-page app campaign is in when the content is delivered to the visitor's browser. For SPA campaigns it is automatically mapped to any website URL, so that the content is ready immediately if target node appears, URL gets requested or any other custom condition is fulfilled. As a consequence of early content delivery, we need to send a "content seen" flag to Maxymiser as soon as the campaign is shown:

	Standard	Single-page app
Content Generator (server-side)	Content response is generated Content seen flags are immediately set for campaigns	Content response is generated
Content Rendering (client-side)	Campaign content is delivered Rendering is performed on the page	Campaign content is delivered Rendering is postponed until the test area availability conditions are fulfilled A campaign's content seen flag is sent as soon as the content gets rendered

Step 1 - Define the objective

Start by defining the objective for the campaign – the part of your website that you want to test, and how you will measure the effectiveness of the test.

Just for the sake of example, let's test a CTA:

Default	Alternative

Step 2 - Build campaign

The next step is to create a campaign, set up URL masks, build variants' and actions' code in the Campaign Designer.

Start from a new "Campaign Designer" campaign on Campaigns Dashboard and enable "SPA Support" check-box in Campaign Settings:

Even when you specify the Campaign URLs, visitor specific experience will arrive as soon as a page would start loading, but take effect only when we specify it to. This configuration is defined in the campaign code.

Step 3 - Code experiences

To configure how campaign content is applied to a page, we use the spa module in the campaign script and variant code.

Rendering script code

The following code sets the conditions to apply changes:

spa.when([ spa.conditions.location('*/men/coats-and-jackets/Leather-Moto-Jacket'), spa.conditions.element('#button-cart') ]).then(function() { renderer.runVariantJs(); if (!campaign.scope.contentSeen) { campaign.scope.contentSeen = true; campaign.sendContentSeen(); } });

The callback from .then() method is run as soon as all the conditions passed to .when() method are fulfilled. All the code inside the callback is executed once for every DOM mutation that fulfills the requirements, and stops being executed as soon as at least one of the conditions is not met.

When the required conditions are fulfilled successful rendering should be recorded with campaign.sendContentSeen() method call. Make sure this method is executed only once per page view as shown in the example above.

Variant code

The following code defines the modifications within a variant:

As soon as you select an action for your campaign, it starts appearing on Sandbox:

You can use variant scripts to apply changes with CSS or custom JavaScript methods. In this case you may want to force changes only for your tested area. For instance, CSS rules that are applied on a page, may lead to unpredictable behavior when moving to another location. To fix that you can use .rollback() method where you get back to the proper experience. It is executed every time at least one of the conditions is not met. Native spa module methods don't require any rollbacks.

Tracking actions

You can use the spa.actions.trackClicks() to apply reversible (automatically deactivated when one of the conditions is not met) action click tracking. actions.set() and actions.send() are also applicable, but may need a wrapper to avoid duplicated tracking.

spa.when([ spa.conditions.location('*/men/coats-and-jackets/Leather-Moto-Jacket'), spa.conditions.element('#button-cart') ]).then(function() { spa.actions.trackClicks('#button-cart', { name: 'CTA', value: '1' }); });

Step 4 - QA and publish

The final step of campaign development process is to confirm that campaign content and action tracking works across different browsers and put the campaign live:

Go to the Top

Campaign Design API > SPA campaign development tutorial