How to Migrate to the New SPA Script

Follow

Dynamic Yield is rolling out its new Single-Page Application solution. This article is intended for existing customers that would like to switch to the new SPA solution.

Overview: What's New

 

Current SPA solution

New SPA solution
Page changes/transitions

Had to be explicitly reported using the SPA event

 Automatically detected using MutationObserver and Proxy APIs

Campaign rendering

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

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

Campaigns State

The campaigns aren’t reacting to page changes

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

How to 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 

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.
  • 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 Requestly plugin for Chrome. It allows you to simulate this solution on your browser, without applying it to your site visitors.
  2. In Requestly, create a new rule
  3. Select “Redirect Request” from the popup window
    Screen_Shot_2021-04-13_at_18.34.02.png
  4. In the redirect request creation window:
    1. Give the rule a name, e.g. “Simulate Harmony SPA”
    2. Change the comparator from Match to RegEx
    3. Set the RegEx value to /api_static.js$/gi
    4. Set the destination to https://cdn.dynamicyield.com/scripts/12570/harmony.js.
      if you use the EU data center of Dynamic Yield, set it to https://cdn-eu.dynamicyield.com/scripts/12570/harmony.js
      Screen_Shot_2021-04-13_at_18.37.54.png
  5. Save the rule
  6. Navigate to the website, empty cache, and 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 rendered correctly.
  • Check that SPA page transitions do not break any campaign.
  • 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 it to Your Site on Production

Contact Support to enable it to all of your traffic. Once enabled, you can remove the Requestly rule.