Note: These guidelines are going to updated soon with a more streamlined method. Learn more.
Many websites use Single Page Application technology such as React, AngularJS, and Vue.js. If this is the case for all or part of your website, visitors may navigate through your site from screen to screen without changing the URL. Even if the URL does change, the browser may populate elements dynamically instead of reloading the page.
Dynamic Yield experiences depend on browser pageloads, as most experiences are rendered when their relevant page is loaded. SPAs do not generate pageloads, and therefore Dynamic Yield will not run experiences on affected pages without manually reporting pageviews.
To run Dynamic Yield experiences on pages or sites using SPA, you explicitly inform Dynamic Yield every time a new SPA page is loaded using an API. You indicate which Dynamic Yield campaigns should be affected by the API using an advanced setting in each campaign.
Step 1: Report Pageviews via API
There are two ways to use APIs to report pageviews:
- Use individual spa calls if the pageload is very fast (completed synchronously on the client-side without any delays or calls to the server).
- Use pairs of spa_start and spa_end calls to define the start and end of a pageview. Use this method if the pageload itself is more than a few milliseconds, or if you aren’t sure.
Make the following API call where an SPA pageview is called:
context: The Page Context.
url: Optional. Defaults to the current page URL.
countAsPageview: Optional. Defaults to ‘true’. If set to ‘false’ it will not register as a new pageview in Dynamic Yield reports, but all Dynamic Yield features dependant on pageviews will be updated.
Make the following API call at the start of every pageview:
- context: The Page Context.
- url: Optional. Defaults to the current page URL.
- countAsPageview: Optional. Defaults to ‘true’. If set to ‘false’ it will not register as a new pageview in Dynamic Yield reports, but all Dynamic Yield features dependant on pageviews will be updated.
Make the following API call when the page is fully rendered:
Step 2: Enabling SPA for Relevant Campaigns
After you have implemented SPA API calls, you enable an advanced option for every campaign you want to be affected by these API calls. All other campaigns will not be affected in any way. When creating or editing a campaign, enable the Serve on every SPA event option in the Advanced settings.
Validating SPA Functionality
Use this procedure to verify that you have configured the API calls and the Dynamic Yield settings correctly.
- In your browser, go to Inspect › Network Tab.
- Type SPA in the search bar. This will limit the results of the next step.
- Copy the spa or spa_start API call you created to the console of your browser and click Enter to run it.
- Drill down to see details of the API and make sure there are no errors.
- Make sure the Serve on every SPA event option is enabled for relevant campaigns.
- Simulate an SPA workflow on your site that should contain a Dynamic Yield campaign.
- Inspect your browser to verify that an SPA event was fired.
Troubleshooting SPA Issues
In some cases, an SPA campaign targeted on one page may persist and continue to appear on different pages. If this occurs, we recommend the following workaround:
- Edit the campaign.
- Create a new experience with the lowest targeting priority. This means that the experience will only be served when the targeting conditions of all other experiences are not met. In our case, this means it will only be served on pages that are not your target page.
- Create an empty variation by using the HTML tab and adding an empty set of <div> tags. You can also use the JS tab to create an empty variation.
- Save the campaign and publish the experience.
Now users will continue to be served the campaign on all pages, but since the variation is blank no content will be visible.