React single page applications
These instructions cover SPAs built using React. For general SPA integration documentation, visit this page.
Integrating Rokt into a single page application (SPA) requires more consideration than standard multi-page applications. SPAs preserve the state between page transitions, operating more like native apps than traditional websites.
In the case of a React SPA, Rokt should be launched once as a singleton. When a placement is ready to be rendered, the application can interact with the singleton.
You can use React Context to hold a reference to the singleton. With React Hooks, you can obtain and interact with that singleton reference.
React Context Wrapper
Here is an example of a context provider for Rokt.
import React, { createContext, useContext, useEffect } from "react";
export const RoktLauncherContext = createContext(null);
export function useRoktLauncher() {
return useContext(RoktLauncherContext);
}
export function RoktLauncherContextProvider({
children,
accountId,
sandbox = false,
}) {
const [launcher, setLauncher] = useState(null);
useEffect(() => {
(async () => {
// Guards against Rokt script being still loaded into the application when the context is created
await new Promise((resolve) =>
window.Rokt
? resolve()
: (document.getElementById("rokt-launcher").onload = resolve)
);
const launcherInstance = await window.Rokt.createLauncher({
accountId: accountId,
sandbox: sandbox,
});
setLauncher(launcherInstance);
})();
return () => {
if (launcher) {
launcher.terminate();
}
};
}, [accountId, sandbox]);
// Return the context provider
return (
<RoktLauncherContext.Provider value={launcher}>
{children}
</RoktLauncherContext.Provider>
);
}
Consuming Context
Application Root
Wrap your App
component in this context provider:
ReactDOM.render(
<RoktContextProvider accountId="YOUR_ROKT_ACCOUNT_ID" sandbox={true}>
<App />
</RoktContextProvider>
);
You have to remove the sandbox
flag or set it to false
when deploying to production.
On the Route
On the page that shows the Rokt placement, use the Rokt singleton and tell it to trigger a Rokt selection:
import React, { useEffect, useRef } from "react";
// Imagine this is the component for the confirmation page route
export function ConfirmationPage() {
// Obtain the relevant attributes to pass to Rokt from an internal location
const attributes = useAttributes();
const launcher = useRoktLauncher();
useEffect(() => {
// Return if launcher not initialized or integration attributes not present
if (!launcher || !attributes.email) {
return;
}
const selectionPromise = launcher.selectPlacements({
attributes: attributes,
identifier: "confirmation.page",
});
return () => {
if (selectionPromise) {
// When the page closes, remove all the Rokt placements
selectionPromise.then((selection) => selection.close());
}
};
}, [launcher, attributes]);
return (
<div>
<h1>Confirmation Page</h1>
<div id="rokt-placeholder" />
</div>
);
}
If you are a Rokt Ads client looking to report conversion, please reference this code example when consuming the context:
import React, { useEffect, useRef } from "react";
// Imagine this is the component for the confirmation page route
export function ConversionPage() {
// Obtain the relevant attributes to pass to Rokt from an internal location
const attributes = useAttributes();
const launcher = useRoktLauncher();
useEffect(() => {
// Return if launcher not initialized or integration attributes not present
// This example also checks for the presence of a passbackconversiontrackingid value
if (
!launcher ||
!attributes.email ||
!attributes.passbackconversiontrackingid
) {
return;
}
const selectionPromise = launcher.selectPlacements({
attributes: attributes,
identifier: "conversion.page",
});
}, [launcher, attributes]);
}