What is a single-page app (SPA)?
Definition
A single-page application is a website usually developed with a modern JavaScript client-side framework (React, Next.js, Vue.js…) and usually doing server-side rendering (SSR), which makes client-side implementations more difficult. The purpose is to improve the navigation experience of the visitor, and avoid loading a new page after every action.
But not all cases of single-page involve an entire website. There are two possible cases:
- your entire website is a single-page app;
- a part of your website is a single-page app (the shopping funnel, for example).
We will further detail the procedures to be followed in each case.
Impact on experiments built with the graphic editor
Each case may have an impact on experiments built with our graphic editor because our application file (kameleoon.js) will only load at the first page seen by the visitor. If the SPA dynamically renders a new content on a page or if a visitor browses from one page to another, Kameleoon is simply not aware of it.
We will further detail the procedures to be followed in each case.
If your website is a full single-page app
You will need to activate a specific option in the Configuration page of your project.
To access it, click on “Projects” in the Admin menu of the Kameleoon App.
On card of your project, click on “Configuration”.
At the bottom of the “General” section you will find the Advanced settings.
Activate the “Enable support for dynamic websites” option.
It will allow Kameleoon to:
- detect visitor navigation between pages by observing dynamic URL changes. When a change occurs, Kameleoon reloads its entire engine. The behavior of Kameleoon is well explained in our Developers documentation.
- monitor new SPA updates by using MutationObserver on the SPA (even though the page URL does not change at all) so that we can apply (or reapply) variation changes when something has changed on your website. Kameleoon currently supports the following actions done with the graphic editor: style changes, wording modification, position updates (swap, insert after / before), use of custom CSS selectors, etc.
- automatically avoid any element ID that have a dynamically generated number with more than 5 digits when selecting the element on the page.Kameleoon will rather generate a unique path from the closest parent element (that is considered as static and has an ID) to the element you want to change.
Set a custom attribute
Optionally, you can set your own way of selecting an element on a page by indicating a custom attribute (eg. data-id, data-qa, …). This option is recommended if your website generates dynamic IDs for each HTML element.
The Graphic Editor uses CSS selector paths to identify the elements on the page you have changed (for example, changing color values or editing text). Kameleoon uses two types of CSS selector paths:
- If an
idfor the selected element exists, then Kameleoon uses it to identify the element when the page loads, and Kameleoon will apply the changes to it. - If Kameleoon doesn’t find an ID for the selected element, a combinator selector will be created from the closest parent element that has an ID.
If your IDs change during dynamic updates, the Graphic Editor may not correctly identify the elements to change. This option allows you to set a static ID attribute name (for example, custom-id) that you can apply to your HTML elements (<button custom-id=”1”>) that uniquely identifies the elements.
If a part of your website is a single-page app
For example, only your funnel may be a single-page app.
You need to use the following code in the global script of your Kameleoon site:
if (location.href.indexOf("mySPAWebsitePart") != -1)
{
Kameleoon.API.Core.enableSinglePageSupport();
}
With that code, Kameleoon will catch the navigation between each step of your funnel and reload its engine to execute back all your experiments.
(Replace “mySPAWebsitePart” by the URL of your funnel)
REACT and JS SDKs
Kameleoon also provides a REACT SDK and a JS / Typescript SDK for single-page apps. It enables a developer to use an alternate way of running experiments / feature flags on your application via the use of an SDK implemented within your single-page app.
You can refer to each SDK documentation to check out all possible features for your single-page app.
GatsbyJS plugin
We also provide a dedicated Kameleoon plugin that can be used with any GatsbyJS app. Please follow this documentation.
Activation API
You can also run experiments / feature flags on your application by using our JS Activation API. Read more about it
Next.js framework
When using Kameleoon Web Experimentation solution with Next.js, it’s essential to consider how changes made through the graphic editor might affect the page’s DOM. Next.js relies on server-side rendering and client-side hydration to maintain consistency between server and client-rendered content. If Kameleoon modifies the DOM too quickly after changes are made, it may disrupt Next.js’ hydration process and lead to page breakage, especially when using frameworks like Vue.js.
To mitigate this issue, it’s recommended to add an attribute to the <body> element once the page is hydrated. This attribute signals to Kameleoon that the page is ready for DOM modifications, preventing potential conflicts with Next.js hydration. Additionally, you can utilize Kameleoon’s command queue, triggered with Events.trigger(‘my page is hydrated’), to ensure synchronized actions with Next.js. You can then use the targeting criteria “Custom event” in your experiments. For more details on implementing custom events and other targeting criteria in Kameleoon experiments, refer to the documentation here.
