Edit

Single Page Applications

The process of integrating Rokt with a Single Page Application website differs from the process of integrating with Multi Page Application websites. Different Single Page Applications approach page transitions differently so this guide will focus on how to use the Rokt service more generally. Developers will need to apply these principles to their framework of choice.

For Single page applications we offer two integration options.

  1. (Recommended) Pre-Initialize Rokt when customers first arrive on the Single Page Application and then trigger placement and offer selection once the customer reaches the virtual page/view where Placements will be rendered
  2. Initialize Rokt on the virtual page/view where placements will be rendered, and pass the timestamp of when the virtual page transition occurred
    • 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 Placements load time on the page(s) where they are rendered. Both options are outlined in more detail below.

Option 1: Pre-initialize Rokt (recommended)

Rokt Service Diagram

1. First Launch of Rokt Service

The Rokt service should be initialized once when a customer first arrives on a Single-Page Application and the service reused throughout the customer’s journey on that site.

When first initialized, the Rokt service will prepare 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 and user device only needs to do the minimal amount required to display the Placement.

To initialize the service simply include the Rokt snippet in the <head> of the website and instruct the service to skip its initial selection. Please refer to other examples for guidance on passing additional configuration to Rokt.

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

2. Arriving on a Page with a Placement

When the customer arrives at a page with a Placement, this is considered critical and time-sensitive. 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 will ensure the html elements the offers are to be placed on 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'
    });
  });
}

3. Leaving a Page with a Placement

Before leaving a page with Rokt Placement(s), the partner site needs to trigger a method on the Rokt Service which will 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.

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();
    });
}

Closing the Rokt Service

If a developer wishes to close the Rokt service they may do so by calling the destroy method on the rokt object.

This will close the Rokt singleton and ensure there are no references to the Rokt Service remaining on the page.

function closeRoktService() {
    window.rokt && window.rokt.onLoaded(function(rokt) {
        rokt.destroy();
    });
}

Option 2: Initialize Rokt on the virtual page and pass timestamp for page view start

The integration follows the same steps as in the previous examples, but adds an additional pageInitTimestamp parameter to be passed to the initialisation function. The value passed should be 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 page view start until Rokt content is rendered. We continuously do work to improve the performance of the Web SDK, so being able to accurately measure the Time to Interactive of placements shown on your site is critical to monitor and improve load times to optimize your customers’ experience and maximize the value Rokt will provide.

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