Integrate your application form
Summary of integration requirements:
- Provide an application URL that is renderable in an iFrame.
- Update your application content security policy (CSP).
- Implement real time application event signals.
- Integrate a conversion tracking solution.
Rendering the application in an iFrame
Rokt manages a wrapper plugin that embeds the application form within an iframe to enable applications directly on top of a partner page. This plugin proxies communication with the Web SDK as well as the partner page. The credit card application plugin is hosted on the provider’s domain and should be a standard web application using whichever framework you prefer. For each credit card or product, you must provide an application form URL. Interaction between the credit card application page and the Rokt plugin is enabled via browser-based message passing. Rokt's credit card plugin is responsive, and will resize and center the credit card application to fit user's screens as well as create backdrop gradients.
To summarize, the Rokt provider plugin (iFrame):
- 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.
Content security policy considerations
Please confirm that your credit card application form's content security policy (CSP) allows for 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 form as a cross origin iframe -- which means Rokt is only able to interact with the page through explicit permissions given by the page’s CSP. In the CSP definition, we recommend that you explicitly list https://apps.rokt.com in the frame-ancestors section. This ensures that only the Rokt domain is granted the ability to embed the application form. In doing so you are protected from injection of third party scripts on your webpage.
Real time application decisions
The credit card application process should communicate application decisions (like instantly approved, pending, or disapproved) with Rokt in real time via the plugin's API, this ensures we 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. More details are available in the conversion tracking section of this document.
Rokt provides a mechanism for card providers to send event signals to represent user interactions with the browser. These signals allow Rokt to respond to user interactions and trigger state changes on the placement (for example displaying a success message when customers complete the application).They also provide important event data for reporting and anomaly detection. Rokt has no visibility into application form content or the customers interactions with your form. Therefore, we rely on the application form sending us status information to the parent window to enable report on application progress and success, as well as monitor when they have completed or exited the form in order to collapse the window.
| Signal | Description |
|---|---|
| Application Initiated | The application form was loaded and is ready for user interaction. |
| Application Closed | User closes the application. |
| Application Approved | The user’s application is instantly approved in real time. |
| Application Pending | The user's application is pending review by the provider. |
Sending status messages
Rokt cannot access any content in your application form and that is why it is important that your application communicates with Rokt to inform us about the status of the customer’s application.
During the lifecycle of your application flow Rokt expects to receive three messages: “Initiated” “Approved” or “Pending” “Closed”
Messages are sent via PostMessage to the Rokt window, for example:
roktWindow.postMessage({ type: 'initiated' }, ‘https://your.domain.com’);
- For security reasons, we recommend providing a specific
targetOriginon eachpostMessage, avoid using*. Rokt will ignore any message which does not originate from your domain. - For security reasons, Rokt won’t send any messages back to your application, therefore your application should not listen to any “message” events.
- Your application will be opened by Rokt. The Rokt window reference is in
window.opener. Nonetheless, it is possible that the opener is not provided, in that case you should fallback towindow.parent.
const roktWindow = window.opener || window.parent; roktWindow.postMessage(...);
Messages
Initiated message
Rokt will expect an initiated message as soon as your application is loaded.
The message data is { type: 'initiated' }
It is very important for Rokt to receive this message to know that your application form has been rendered. Absence of this message will be considered an anomaly and will warrant an investigation from Rokt.
Progress status message
Rokt will expect a pending or approved message, depending on the result of the application.
Pending should be sent if the user completes your application, but you cannot approve that application immediately.
The pending message data is { type: ‘pending’}.
Approved should only be sent if you are able to instantly approve the user's application for your product.
The approved message data is { type: ‘approved’ }.
The status change message must only be sent if the user submits the application form. Do not send a pending or approved signal if the customer exits without submitting the form.
Close message
Rokt will expect a close message whenever the user closes the application form, regardless of if the application has been completed. Rokt will unload your window as soon as a close message is received.
The close message data is { type: ‘close’ }
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);
},
close() {
roktWindow.postMessage({ type: 'close' }, targetOrigin);
},
approved() {
roktWindow.postMessage({ type: 'approved' }, targetOrigin);
},
pending() {
roktWindow.postMessage({ type: 'pending' }, targetOrigin);
},
};
})(/* your page domain here */);
// After load or as soon your application is ready / interactive
roktIntegration.initiated();
// ,,, user completes your application
// If the application was approved by your system
roktIntegration.approved();
// If the application was denied or it is pending to further analysis
roktIntegration.pending();
// Before terminating the application
roktIntegration.close(); // Close message will close your window for you.
Alternatively, you may implement the following:
// After load or as soon your application is ready / interactive
(window.opener || window.parent).postMessage({ type: 'initiated' }, /* your page domain or */ window.location.origin);
// ,,, user completes your application
// If the application was approved by your system
(window.opener || window.parent).postMessage({ type: 'approved' }, /* your page domain or */ window.location.origin);
// If the application was denied or it is pending to further analysis
(window.opener || window.parent).postMessage({ type: 'pending' }, /* your page domain or */ window.location.origin);
// Before terminating the application
(window.opener || window.parent).postMessage({ type: 'close' }, /* your page domain or */ window.location.origin); // Close 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:
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.
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.