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 unload each page between navigations and reload all resources when you arrive on the next page.
If your site is not a single page application, follow our standard integration instructions.
Integration options
If your SPA is built using React, you can follow these instructions.
The process of integrating Rokt with an SPA differs from the process of integrating with traditional multi-page websites. Different SPAs approach page transitions differently, so this guide focuses on how to use the Web SDK more generally. Developers should apply these principles to their framework of choice.
For SPAs, we offer two integration options.
- (Recommended) Pre-initialize the Web SDK when customers first arrive on the SPA, then trigger placement and offer selection once the customer reaches the place where placements are rendered.
- Initialize the Web SDK on the view where placements are rendered. Make sure to include 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
First launch of the Web SDK
The Web SDK Integration Launcher should be initialized when a customer first arrives on an SPA. The service can be reused throughout the customer’s journey on the site.
When first initialized, the Integration Launcher 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 service only needs to do the minimal amount required to display the placement.
To initialize the service, you need to load the Rokt integration onto your page and create an instance of the Integration Launcher.
Loading the integration
As per the multipage application example, the Rokt Integration Launcher can be loaded onto your page by including Rokt script tag in the <head> of the website.
<head>
<script
async
crossorigin="anonymous"
id="rokt-launcher"
fetchpriority="high"
src="https://apps.rokt.com/wsdk/integrations/launcher.js"
type="module"
></script>
</head>
Alternatively, you can add the following snippet of code into JavaScript logic already delivered to your application.
const target = document.head || document.body;
const script = document.createElement("script");
script.type = "text/javascript";
script.src = "https://apps.rokt.com/wsdk/integrations/launcher.js";
script.fetchpriority = "high";
script.crossOrigin = "anonymous";
script.async = true;
target.appendChild(script);
Creating an instance of the Integration Launcher
If you are copying the below example, ensure roktAccountId is replaced with your account's unique ID. You can get your roktAccountId from your account manager or in One Platform.
const launcherPromise = new Promise((resolve, reject) => {
script.onload = () =>
resolve(window.Rokt.createLauncher({ accountId: "rokt-account-id" }));
script.onerror = (error) => reject(error);
});
The reference to the launcher promise should be stored in order to be re-used later in the application flow. It could be done by assigning it to a global state, providing it as a React Context, Angular Service or any way appropriate to your framework of choice.
A Promise is used in this example to guard against a user refreshing your application on a page where the launcher is used. This scenario could cause a race condition in which the launcher instance is used by the page before the instance is actually created. By storing a promise and loading it later in places where the instance of the Integration Launcher is meant to be used, we can guarantee it will be ready each time.
Arriving on a page with a placement
When the customer arrives at a page with a placement, it should load seamlessly. The Integration Launcher service should be running at this point and the site only needs to trigger the offer selection.
The selection can be triggered when the page with a placement loads. The Rokt Web SDK provides a grace period to ensure the anchor HTML element for an embedded placement had a chance to be rendered.
If the anchor element render can be delayed on your page, e.g. susceptible to additional XHR requests which could further delay it, you may want to wait until the anchor element is rendered before triggering a selection.
Most frameworks have a lifecycle hook indicating the view has rendered.
For example: In Angular, developers would use ngAfterViewInit(), and in React, developers can use useEffect() hook or componentDidMount() method.
async function afterPageElementsHaveRendered() {
const launcher = await launcherPromise;
const selection = await launcher.selectPlacements({
attributes: {
email: "j.smith@example.com",
},
identifier: "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 return argument or componentWillUnmount().
async function beforeNavigatingAwayFromPage() {
selection.close();
}
Initializing Rokt on a virtual page
The integration follows the same steps as the main example. However, it may require that you both add the Rokt script dynamically to the page, as well as ensure users don't create extra instances of the Integration Launcher when they re-visit the page.
Adding pageInitTimestamp to the initialization on a virtual page helps Rokt to measure performance relative to your SPA page transition. The value 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.
// Integration steps as per other examples
const launcher = await launcherPromise;
const launcher = await createLauncher({
accountId: "roktAccountId",
pageInitTimestamp: Date,
});