Edit

Integrating the Web SDK on single page applications

If your website is built as a single page application (SPA), follow these guidelines for a smooth integration.

What is a single page application?

A single page application is a web application (or website) that facilitates page transitions by dynamically rewriting a single web page. This improves performance and makes the web application feel more native.

Additionally, SPAs load all site resources (aside from assets like images, videos, and copy) upon arrival to the site. Then they simply retrieve the page-relevant information when a customer navigates to that page. SPAs typically have an increased initial site load time, but near-instant page transitions. Common examples of SPAs that you use every day include Gmail, Netflix, Twitter, and Rokt’s One Platform.

In contrast, conventional multi-page applications (MPAs) unload each page between navigations and reload all resources when you arrive on the next page.

Integration options

The process of integrating Rokt with a SPA websites differs from the process of integrating with MPA websites. Different SPAs approach page transitions differently, so this guide focuses on how to use the Rokt service more generally. Developers should apply these principles to their framework of choice.

For SPAs, we offer two integration options.

  1. (Recommended) Pre-initialize Rokt when customers first arrive on the SPA, then trigger placement and offer selection once the customer reaches the place where placements are rendered.
  2. Initialize Rokt on the view where placements are rendered, and pass the timestamp for the virtual page transition.
    • For this option we’d also recommend using the preparative iframe to preload Rokt assets when customers first arrive on the SPA, as this will improve the placement load time. Both options are outlined in more detail below.

Pre-initializing Rokt

Rokt Service Diagram

First launch of the Rokt service

The Rokt service should be initialized when a customer first arrives on an SPA, and the service can be reused throughout the customer’s journey on the site.

When first initialized, the Rokt service prepares everything it needs to display a placement ahead of time. This ensures that when the customer arrives at the time-sensitive moment of placement presentation, the Rokt service only needs to do the minimal amount required to display the placement.

To initialize the service, include the Rokt snippet in the <head> of the website and instruct the service to skip its initial selection. Refer to other examples for guidance on each type of Web SDK configuration.

<head>
  <script>
    (function(r,o,k,t,n,e,w,a,_){r._ROKT_=n;r[n]=r[n]||{id:t,h:w,lc:[],it:new Date(),onLoaded:function(c){r[n].lc.push(c)}};a=o.createElement('script');a.type='text/javascript';a.async=!0;a.src=k;if(e){a.integrity=e;a.crossOrigin='anonymous'}_=o.getElementsByTagName('script')[0];_.parentNode.insertBefore(a,_)})(window,document,'https://apps.rokt.com/wsdk/integrations/snippet.js','roktTagid', 'rokt');

    rokt.onLoaded(function(rokt) {
      rokt.init({ skipInitialSelection: true });
    });
  </script>
</head>

Arriving on a page with a placement

When the customer arrives at a page with a placement, the placement load experience should be seamless. The Rokt service should be running at this point, and the site only needs to trigger the offer selection after the page has completed its transition.

Developers must trigger the offer selection process after the page view has initialized. This ensures the anchor HTML elements for each placement have been rendered on the page.

Most frameworks have a lifecycle hook indicating the view has rendered.

For example: In Angular, developers would use ngAfterViewInit(), and in React, developers bind to the ref of the target element, or they can use the componentDidMount() method.

function afterPageElementsHaveRendered() {
  window.rokt && window.rokt.onLoaded(function(rokt) {
    rokt.setAttributes({
      email: '',
    });

    rokt.triggerPageChange({
      pageIdentifier: 'checkout.page'
    });
  });
}

Leaving a page with a placement

Before leaving a page with Rokt placements, the partner site needs to trigger a method on the Rokt service to remove placements on the current page and perform cleanup.

Most frameworks have a lifecycle hook indicating that a page is about to be navigated away from. For example: In Angular, developers would use ngOnDestroy(), and in React, it can be in the form of a useEffect() hook or componentWillUnmount().

function beforeNavigatingAwayFromPage() {
    window.rokt && window.rokt.onLoaded(function(rokt) {
        rokt.closeAll();
    });
}

Initializing Rokt on a virtual page

The integration follows the same steps as in the previous examples, but adds an additional pageInitTimestamp parameter to be passed to the initialization function. The value passed should be a JavaScript Date object that indicates the timestamp of when the virtual page transition occurred. The benefit of providing this information is so that we can accurately measure the time it takes from a customer to start viewing a page to when Rokt content is rendered. We continuously work to improve the performance of the Web SDK, so being able to accurately measure the placement Time to Interactive (TTI) on your site is critical to monitor and improve load times and optimize your customers’ experience, maximizing the value Rokt can provide.

rokt.onLoaded(function(rokt) {
    rokt.init({
       pageInitTimestamp: '',
       pageIdentifier: ''
    });
    // Integration steps as per other examples
});
← Preparative iframePage identifier →