How to Migrate to the New SPA Script

Follow

Use this article to help switch to the new Dynamic Yield Single-Page Application (SPA) solution.

Overview: Comparing the old and new SPA implementations

 

New SPA solution

Old SPA solution
Page changes/transitions Automatically detected using MutationObserver and Proxy APIs

Had to be explicitly reported using the SPA event

Campaign rendering

 Rendered into the Shadow DOM which is invisible to the front-end framework 

Rendered directly into the DOM, causing frontend frameworks with DOM change detection to remove the inserted campaigns

Campaigns State

The campaigns reevaluate their targeting conditions and rendered or removed from the page upon detection of page changes

The campaigns aren’t reacting to page changes

Migrate to the new SPA solution

The migration includes 4 steps:

  1. Review your campaigns, and if needed, make changes.
  2. Simulate the new solution on your site.
  3. QA the changes you made to your campaigns.
  4. Contact Support to enable the new solution on your production site.

Prerequisite: Having page context implemented is mandatory for this feature.

Step 1: Review and edit existing campaigns

  • Third-party libraries should pass references to elements instead of CSS selectors (In the new solution, the campaigns are rendered into a shadow dom).
    For example, instead of passing a selector to the Swiper carousel plugin: 
    new Swiper('#dy-recommendations-slider', getSliderOptions());
    Pass the actual element:
    new Swiper(document.getElementById(dy-recommendations-slider'), getSliderOptions());
    Make sure to review all of your variations and the templates.
    Note that you must also update the Swiper's option object to ensure that it works as expected with the new SPA script.
  • If you have Dynamic Content or Recommendations campaigns that are implemented manually via embed code, embed them automatically by referencing the selector.
    Screen_Shot_2021-04-13_at_18.31.02.png
  • Implement styles in the variation/template CSS section. It will not inherit styles from the page. CSS from Dynamic Content/Recommendation campaigns won’t affect the DOM elements.

Step 2: Simulate the new SPA solution on your site

  1. Install the Requestly plugin for Chrome. It enables you to simulate this solution on your browser, without applying it to your site visitors.
  2. In Requestly, create a new rule.
  3. In the Create New Rule dialog, select Redirect Request.Screen_Shot_2021-04-13_at_18.34.02.png
  4. In the redirect request creation window:
    1. Give the rule a name, for example Simulate SPA.
    2. Change the comparator from Match to RegEx.
    3. Set the RegEx value to /api_static.js$/gi.
    4. Set the destination to:
      For the US data center:
      https://cdn.dynamicyield.com/scripts/<YOUR_SCRIPT_VERSION_NUMBER>/harmony.js

      For the  EU data center:
      https://cdn-eu.dynamicyield.com/scripts/<YOUR_SCRIPT_VERSION_NUMBER>/harmony.js

      Note that you must specify your current script version in the URL. Check your console by executing DYO.version.
      Screen_Shot_2021-04-13_at_18.37.54.png
  5. Save the rule.
  6. Navigate to the website, empty the cache, and do a hard reload.
    Screen_Shot_2021-04-13_at_18.42.07.png

Step 3: QA your site

  • Look at your Dynamic Content and Recommendations campaigns and QA:
    • Appearance: CSS styling is applied correctly.
    • Functionality:Third-party plugins are passing HTML elements and not CSS selectors.
  • Make sure that Multi-Touch campaigns are rendered correctly.
  • Check that SPA page transitions do not break any campaigns.
  • Edit a template that is linked to active variations, and verify that it updates the variations.

Useful API: DYO.isSpaFlow - To check if the new SPA solution is enabled

Step 4: Enable the solution on your site (in production)

Contact Support to enable it for all of your traffic. After it's enabled, you can remove the Requestly rule.