Integrate your embedded web application

Summary of integration requirements:

• Provide a URL for a web application that can be rendered within an iFrame.
• Update your web application’s content security policy (CSP) to allow hosting in Rokt’s domain.
• Implement real time message signals that enable Rokt to respond to state changes.
• Integrate a conversion tracking solution.

Rendering the embedded web application in an iFrame

Rokt manages a wrapper plugin that embeds your web page within an iFrame, enabling seamless interactions directly on top of a partner page. This plugin facilitates communication between the Web SDK and the partner page and provides a security isolation boundary between your page, Rokt and the partner page. The embedded action plugin is hosted on your domain and should be built as a standard web application using your preferred framework. For each product or service you offer, you must provide a URL.

Interaction between your web page and the Rokt plugin is enabled via browser-based message passing. The Rokt embedded action plugin is responsive — it resizes and centers the page to fit the user’s screen while applying backdrop gradients for a seamless integration.

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

Content security policy considerations

Ensure that your web application’s content security policy (CSP) allows hosting via Rokt’s domain: https://apps.rokt.com. Otherwise, Rokt’s plugin will be unable to host the application form.

Rokt loads the provided URL as a cross-origin iFrame. This provides security sandboxing where you maintain maximum control over your page. If you use CSP's, you will need to explicitly grant Rokt (https://apps.rokt.com) permission to render your page in an iFrame using the frame-ancestors directive. This directive needs to be added only for pages rendered in the Rokt iFrame.

Real time message signals

Rokt provides a mechanism for your web application to send real-time message signals representing user interactions within the browser. These signals allow Rokt to:

• Respond dynamically: For example, display a success message when a customer completes a transaction.
• Trigger state changes: Such as collapsing the window when the iFrame is closed.
• Collect important data: Ensuring that Rokt can render the most relevant placement content and track user progress accurately.

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. More details are available in the conversion tracking section of this document.

Below is a table of the supported signals and their descriptions:

Website Action	Description	Integration Required
Initialized	Sent when the landing page successfully loads and the site is ready for interaction.	True
Complete Registration	Sent when a user has successfully submitted information in exchange for service provided by your business. For example, registered for an account	False
Logged In	Indicates that a user has successfully authenticated their account.	False
Lead	Sent when a customer submits information (e.g., signing up for a trial or completing a form) with the understanding that they may be contacted later.	False
Subscribe	Sent when a user initiates a paid subscription for one of your products or services.	False
Application Submitted	Sent when the user submits a credit card application	True only for credit card offers
Application Approved	Sent when the user’s credit card application is instantly approved in real time.	True only for credit card offers
Completed	Sent when the user successfully completes the desired action on your advertiser site (e.g., finalizing a purchase).	True
Provider Close	Sent when a user exits the form by returning to the checkout (e.g., clicking the “return to checkout” button).	True

Sending message signals

Due to the security sandbox provided by the cross-origin iFrame, Rokt cannot access the content within your web application. Therefore, it is crucial that your form communicates its status by sending message signals using the browser's postMessage API to the Rokt window. For example:

roktWindow.postMessage({ type: 'initiated' }, ‘https://your.domain.com’);

IMPORTANT

• Always provide a specific targetOrigin on each postMessage call (avoid using *). For security reasons, Rokt will ignore messages that do not originate from your specified domain.
• Rokt does not send any messages back to your web application, so you should not listen for “message” events.
• Your web application is opened by Rokt, with the window reference available in window.opener. If this is not provided, fall back to window.parent.

const roktWindow = window.opener || window.parent; roktWindow.postMessage(...);

Messages

Form initialization

Rokt will expect an 'initialized' message as soon as your application is loaded.

IMPORTANT

It is critical for Rokt to receive this message to know that your web page has been rendered. Absence of this message will be considered an anomaly and will warrant an investigation from Rokt.

Progress messages

Rokt accepts the following "progress" messages to track steps in a user's conversion journey. These can be helpful for reporting and campaign optimization. At a minimum, the completed message is required to indicate the user completed the desired action on your site (e.g. finalizing a purchase).

• Use 'loggedIn' when a user successfully signs into their account.
• Use 'completeRegistration' when a user completes their registration process.
• Use 'subscribe' when a user initiates a paid subscription for one of your products or services.
• Use 'lead' when a customer submits information (e.g., signing up for a trial or completing a form) with the understanding that they may be contacted later.
• Use 'applicationSubmitted' when a customer submits their credit card application
• Use 'applicationApproved' when a customer's credit card application is instantly approved

IMPORTANT

At a minimum, the completed message is required to indicate the user completed the desired action on your site. For credit card advertisers hosting an application form on Rokt, applicationSubmitted and applicationApproved are required to optimize application to approval rates.

Exiting the form

Rokt expects a providerClose message whenever the exits the form, regardless if desired action has been completed. Rokt will unload your window as soon as a close message is received.

IMPORTANT

Users may close the application form by interacting with one of the form's buttons. If your form does not have a "close" button and you rely on the "X" button in the Rokt plugin iFrame to close your application, then you are not required to send this signal.

Implementation examples

This implementation example can be used directly on your application:

const roktIntegration = (function(origin) {    
  const targetOrigin = origin || window.location.origin;    
  const roktWindow = window.opener || window.parent;    

  return {    
    initiated() {
      roktWindow.postMessage({ type: 'initiated' }, targetOrigin);
    },  
    loggedIn() {
      roktWindow.postMessage({ type: 'loggedIn' }, targetOrigin);
    },  
    completeRegistration() {
      roktWindow.postMessage({ type: 'completeRegistration' }, targetOrigin);
    },  
    applicationSubmitted() {
      roktWindow.postMessage({ type: 'applicationSubmitted' }, targetOrigin);
    },  
    applicationApproved() {
      roktWindow.postMessage({ type: 'applicationApproved' }, targetOrigin);
    },  
    completed() {
      roktWindow.postMessage({ type: 'completed' }, targetOrigin);
    },  
    providerClose() {
      roktWindow.postMessage({ type: 'providerClose' }, targetOrigin);
    }  
  };    
})(/* your page domain here */);
   

// Example usage:  
// On landing page load  
roktIntegration.initiated();  

// When the user logs in  
roktIntegration.loggedIn();  

// When a new account is created  
roktIntegration.completeRegistration();  

// When the credit card application form is submitted  
roktIntegration.applicationSubmitted();

// When the credit card application form is approved  
roktIntegration.applicationApproved();  

// When an action is completed  
roktIntegration.completed();  

// When the user completes the process via the "return to checkout" button  
roktIntegration.providerClose();

Alternatively, you may directly send messages without the wrapper:

const roktWindow = window.opener || window.parent;

// On landing page load:
roktWindow.postMessage({ type: 'initiated' }, /* your page domain or */ window.location.origin);

// On user login:
roktWindow.postMessage({ type: 'loggedIn' }, /* your page domain or */ window.location.origin);

// On account creation:
roktWindow.postMessage({ type: 'completeRegistration' }, /* your page domain or */ window.location.origin);

// On credit card application form submission (if applicable):
roktWindow.postMessage({ type: 'applicationSubmitted' }, /* your page domain or */ window.location.origin);

// On credit card application approval (if applicable):
roktWindow.postMessage({ type: 'applicationApproved' }, /* your page domain or */ window.location.origin);

// On action completed:
roktWindow.postMessage({ type: 'completed' }, /* your page domain or */ window.location.origin);

// On exit or return to checkout:
roktWindow.postMessage({ type: 'providerClose' }, /* your page domain or */ window.location.origin); // providerClose message will close your window for you

Conversion Tracking

Advertisers and providers are required to integrate a conversion tracking solution. Setting up automatic conversion reporting helps you measure the impact of your campaigns on your business. Rokt offers a variety of ways to integrate your conversion data. For greatest accuracy, we recommend using the Rokt Web SDK or Event API. The instructions for each method are listed below:

• Web SDK
• Event API

Although it is not recommended, you can alternatively provide conversion data via manual file upload. Delayed conversion data should only be used when no other conversion tracking solution is possible, as it has significant implications for our prediction models (i.e. relevancy), restricts access to smart tools, and disrupts reporting & analytics capability.

Pending Approvals

The Web SDK will only track applications which can be approved in real time when the customer submits the application. Pending applications which require further review before an approval decision can be made should still be provided to Rokt so that we can capture all Rokt-attributed conversions. To integrate pending approval data we recommend using the Event API. Using the Event API, your backend server can securely connect to Rokt's, transmitting conversion data once a decision has been made about the success of a credit card application.

Follow these instructions on how to integrate the Event API.

note

In order to properly attribute conversions, you must include one of email (email), SHA-256 hashed email (emailsha256), or Rokt Tracking ID (passbackconversiontrackingid) in objectData so that Rokt can identify the customer. Rokt Tracking ID is the preferred identifier for most financial services institutions that advertise with Rokt.

Security and Privacy

Ownership of application data

Your page is rendered in a cross-domain iframe to provide a security sandbox. Rokt and its partners will not be able to access or receive your application form data. The information customers enter into the application form will only be provided to you and stored by you on your own servers. Users may, of course, choose to share the same or similar information with partners directly on the ecommerce page. Much of the same information, such as name and address, is required to complete a purchase on the originating partner site. You will not have access to any customer PII data provided by customers directly to partners.

Storage of application data

Rokt does not have access to customer data entered into your application form. Therefore, customer data is not stored on Rokt servers for integrated application campaigns.

Rokt security policies

Listed below are some security measures intentionally implemented by Rokt to mitigate vulnerabilities and protect you from any form of communication with your webapp except through explicitly defined postmessage implementations.

• Although Rokt will never attempt to access the content of your application, Rokt will set the most secure CSP configuration for the iFrame hosting your application, making it impossible for external access.
• Rokt uses a Channel Messaging API on both sender and receiver sides. This is to prevent third parties from sending or receiving messages through window.postmessage().
• Rokt does not send any credentials or tokens via window.postmessage().
• Rokt will not use any type of communication channel, which means your application does not need to listen to “message” events.
• Rokt implements frame-ancestors CSP directive to defend against clickjacking.

Rokt has a detailed process for handling any security incidents, which includes a complete internal review of any incidents.