Last updated Oct 24, 2023

Credit Card Integration with Rokt

Integration overview

note

This integration document describes some of the specific integration capabilities Rokt can provide. It is not an exhaustive list of current or potential integration methods. Speak with your Account Director to discuss in greater detail.

Rokt will render your application flow within an iframe hosted by the Rokt credit card provider overlay plugin. This plugin:

• Proxies communication with the Web SDK as well as the parent page.
• Is hosted on your domain and should be a standard web application.
• Must include the application page url in the data fields for each unique credit card you will offer via Rokt.

Interaction between the credit card application page and the Rokt plugin will be enabled via browser based message passing. Specific implementation details with code samples are included below.

Real time application decisions

The credit card application process should communicate application decisions with Rokt in real time via the plugin's API, in order to render relevant placement content. For any pending decisions that are later resolved, you should communicate these results back to Rokt via the Event API or another data delivery mechanism.

Hosting your application in an iframe

To enable third-party credit card applications workflows directly on top of a partner page, Rokt manages a wrapper plugin that embeds the target credit card application form within an iframe.

Content security policy considerations

Please affirm that your credit card application form's content security policy allows for hosting via Rokt's domain: https://apps.rokt.com. Otherwise, Rokt’s plugin will be unable to host your application form on the relevant pages.

Iframe size

Rokt's credit card plugin will resize and center the credit card application to fit user's screens as well as create backdrop gradients.

Removal on plugin timeout

Rokt observes the status of the loaded iframes/plugins to ensure the best user experience should anything prevent the iframe from loading correctly. For this reason, the Rokt Web SDK starts a timer waiting for the MessagePort handshake once the target plugin has issued its onload event. This ensures Rokt’s Web SDK can remove the plugin if there is a timeout indicating it has hung.

Attributes applied to the <script> tag will trigger the document’s onload event prior to the complete evaluation of the JavaScript within the target script. This means slower devices may take longer to evaluate the JavaScript than our timeout allows for. For this reason, it’s important that the <script> containing the plugin initialization logic is loaded synchronously.

Communicating via messages

note

At the end of this document is an implementation that demonstrates this handshake and can be copied directly into the target application. The following will explain this handshake in greater detail.

Message format

Rokt’s Web SDK will send data to the target plugin via the browser’s postMessage API through the MessagePort obtained after the initial handshake.

The details of the message will be provided in the event.data property on the event and will adhere to the following structure:

type PluginMessage = {
  type: PluginMessageAction
  payload?: BasicObject
}

Initial connection to the Rokt plugin

In order to securely listen to events coming from the iframe hosted on a Rokt domain, the target plugin must obtain and listen to a MessagePort received on a message event on the window.

This MessagePort will facilitate communications between the two frames, ensuring the events are filtered by domain. This will make sure the target plugin is not opened illicitly by non-Rokt entities.

Here is an example setup of initializing communications with the Rokt Plugin:

// Begin listening for the message port
const onPort = new Promise((res) => {
  function onPort(event) {
    // Filter untrusted domains
    if (event.origin.endsWith(".rokt.com")) {
      window.removeEventListener("message", onPort);
      res(event.ports[0]);
    }
  }
  window.addEventListener("message", onPort);
});

// Blank message indicates to the parent that the
// target plugin is ready to receive the MessagePort
window.parent.postMessage({ type: 'send-port' }, "*");

// When the port arrives
const port = await onPort;

// Begin listening to postMessage events on the port
port.addEventListener("message", (event) => {
  const { type, payload } = event.data;
});

// Instruct the MessagePort to begin sending messages,
// replaying buffered messages
port.start();

// Send a message to the Rokt Web SDK
port.postMessage({ type: "close" });

note

It is important to begin listening for message events before sending the “ready” message

Sending messages to Rokt

The target plugin can send messages to the parent Rokt frame using the postMessage API on the obtained MessagePort.

// ...

port.postMessage({ type: 'close' })

Events

From Rokt plugin to credit card application

• Event Name: config

Sent once when the plugin launches and contains all of the information required to render correctly.

type Payload = {
  creditCard: unknown
  offer: unknown
  partner: {
    name: string
  }
}

note

Reduce application friction for the applicant by pre-filling fields found in the config payload

From credit card application to Rokt plugin

• Event Name: complete

Sent once the customer completes the application, proving a completion status.

type Payload = {
  status:
    'approved' |
    'pending' |
    'declined'
}

• Event Name: interactive

Sent once the plugin’s UI is interactive - defined as rendered and interactable by the user.

This is triggered manually by the plugin and is normally after the initial render cycle of the framework being used.

void

• Event Name: close

Sent once the plugin is ready to be removed from the partner page.

This will stop any further execution of JavaScript within the target plugin as it will be removed from the page.

void

• Event Name: failure

Sent if the plugin fails critically and requires removal from the partner page.

This will stop any further execution of JavaScript within the target plugin as it will be removed from the page.

void

Example FrameTransport Implementation

Below is a wrapper implementation for the MessagePort handshake with a simplified API for consumption. It’s intended as a simple starting point, feel free to copy it, convert it to ES6 classes, TypeScript or use it as is.

export function FrameTransport() {
  const onPort = new Promise(res => {
    const onMessage = (event) => {
      if (event.origin.endsWith(".rokt.com")) {
        window.removeEventListener('message', onMessage)
        res(event.ports[0]);
      }
    }
    window.addEventListener('message', onMessage)
  })

  this.on = async (type, callback) => {
    const port = await onPort
    port.addEventListener('message', event => {
      if (event.data.type === type) {
        callback(event.data.payload)
      }
    })
  }

  this.send = async (type, body) => {
    const port = await onPort
    port.postMessage({ type, payload: body })
  }

  this.listen = async () => {
    const port = await onPort
    port.start()
  }

  window.parent.postMessage({ type: 'send-port' }, '*')
}

Usage:

const transport = new FrameTransport()

transport.on('config', body => {
  console.log(body.creditCard)
})

transport.listen()

transport.send('complete', { status: 'approved' })
transport.send('close')