Last updated Oct 24, 2023

React single page applications

note

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

note

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