Dynamic Yield for Single-Page Applications (SPA) - Early Access

Single-page applications are becoming more and more popular in current web development. Popular SPA (Single-Page Application) frameworks are React, Vue, AngularJS, Ember, or Backbone. If your website is using one of these frameworks - read this article for the recommended implementation method.

Current Guidelines (Deprecated in April 2021)

Dynamic Yield campaigns depend on browser page load, as most experiences are rendered when their relevant page is loaded. Since SPAs do not generate page loads, Dynamic Yield will not run experiences on these pages without manually reporting pageviews.

To overcome this, you need to:

• Implement an API call to let Dynamic Yield know that a new SPA page was loaded.
• Mark which campaigns are relevant for such calls, in the campaign settings.

New Guidelines (early access until April 2021)

With the new solution, the implementation for single-page application is identical to non-Single-Page Applications. There's no need to implement an API call for SPA pageload, or mark which campaigns are relevant for these calls. Moreover, the solution is seamless to the framework.

How it Works (The Technical Details)

The heavy lifting is done by Dynamic Yield:

• Dynamic Yields monitors page elements load, even when the page itself doesn’t fully reload. This is done using a Web API called a MutationObserver, which provides hooks into DOM mutations and enables Dynamic Yield to track when a DOM node is inserted, destroyed or modified. With that, Dynamic Yield applies (or reapplies) changes at the right moment. Once the page deactivates, Dynamic Yield no longer attempts to change the elements on that page.
• Dynamic Yield script has a state machine, and all of the campaigns are stateful smart objects. This way, the script responds to changes in your applications.
• Our elements are added via the Shadow DOM, in a way that doesn’t interfere with your application’s lifecycle.

Diagram of the Current Guidelines and the New Guidelines

To learn more about the difference between the old and the new guidelines - see below a technical diagram.

Known Limitations

1. 1. Older JS libraries may not be supported. Notice that these libraries might be in the Dynamic Yield templates (e.g. Swiper used for carousel experiences). 
   2. The campaign experience's CSS is not inherited from the site CSS and therefore has to be added explicitly in the variation code. 
   3. Setting the page context is mandatory.

Technical Diagram - What Has Changed?

The following diagram shows the difference between the traditional architecture (i.e. static pages), the current SPA architecture, and the new SPA architecture that is in early access.

Page Change/Transition Detection

The SPA solution is using multiple methods to detect changes to the page:

1. URL Changes, using the History API and Hashchange event
2. Attaching a MutationObserver to the body element to observe any changes to the elements
3. Changes detection of the DY.recommendationContext object
   

Campaign Rendering

Dynamic Content and Recommendation campaigns are rendered into the Shadow DOM instead of the DOM directly. As a result, these campaigns do not interfere with the DOM change-detection of the front-end framework.

In order to allow seamless access to HTML elements of these campaigns, the JS code of the campaigns has multiple querying functions overridden, querying first the Shadow DOMs of the campaigns. If no elements are found it will query the DOM as a fallback.

These functions are:

• document.getElementById
• document.querySelector
• document.querySelectorAll