Integration
In-depth knowledge
Testing and Go-live
GET STARTED
Rendering the Brite Client
In this section, we walk through the process of integrating the Brite Client into your environment, focusing on creating a seamless user experience (UX) via our iframe solution. Our goal is to ensure the Brite Client is rendered optimally across all devices, from desktops to mobile phones.
Follow these steps to seamlessly integrate and display the Brite Client within your webpage, ensuring an optimal user experience across all devices.
To start using Brite in your environment, embed our JavaScript SDK on your webpage. This SDK facilitates rendering the Brite Client and subscribing to session events for a dynamic user experience.
Script Tag
Include the following script tag in your HTML to load the Brite JavaScript SDK:
<script src="https://client.britepaymentgroup.com/client.js"></script>
For an optimal user experience, it’s crucial that the HTML container dynamically adjusts to hug the dimensions of the Brite Client iframe. This ensures that the presentation is seamless across all devices, eliminating any possibility of internal scrolling within the container that could detract from the user experience.
To achieve this, your application should follow size changes in the iframe and adjust the container’s dimensions accordingly. This dynamic adjustment is essential to maintain a consistent and engaging user interface, especially when dealing with various device sizes and orientations.
/* Base styles for BritePayment container div */
#BritePayment {
display: flex; /* Enable flexbox */
justify-content: center; /* Center content horizontally */
align-items: center; /* Center content vertically */
position: fixed; /* Fixed position */
top: 0; /* Align to the top of the viewport */
left: 0; /* Align to the left of the viewport */
z-index: 10; /* Ensure it appears above other content */
overflow: hidden; /* Prevent scroll on the container */
}
Desktop and Tablet Devices: The Brite Client is designed with a minimum height of 600px and width of 400px. Note that these dimensions are subject to change and using a dynamic container is recommended.
/* Styles for desktop and tablet devices */
@media only screen and (min-width: 481px) {
#BritePayment {
width: auto; /* Allow the width to grow with the iframe */
height: auto; /* Allow the height to grow with the iframe */
min-width: 400px; /* Minimum width for Brite Client */
min-height: 600px; /* Minimum height for Brite Client */
position: fixed;
top: 50%;
left: 50%;
transform: translate(-50%, -50%); /* Center the div in the viewport */
}
}
/* Media query for mobile phones */
@media only screen and (max-width: 480px) {
#BritePayment {
width: 100vw; /* Occupy 100% of the viewport width */
height: 100vh; /* Occupy 100% of the viewport height */
}
}
Implementation Tips
- CSS Flexbox or Grid: Use them to make your container responsive and flexible. These layouts automatically adjust to their child elements’ size, making them ideal for dynamically sizing the Brite iframe container.
- Viewport Units for Mobile Devices: For mobile devices, ensure the container uses viewport width (vw) and viewport height (vh) units to occupy the full screen. This is crucial for meeting the requirement that the Brite Client occupies the full viewport on mobile devices.
- Don’t obstruct the Brite Client: Additional close buttons or overlay elements that might hinder usability are not allowed.
Example HTML container
<div id="BritePayment"></div>
Example JavaScript
var client = new Brite('session_token');
Once the Brite Client is defined, render the Brite iframe to the user by populating the previously defined container.
Example JavaScript
client.start({
selector: '#BritePayment',
width: '400px', // Override the default Brite Client's width
height: '600px' // Override the default Brite Client's height
color_theme: 'dark', // Optional: Enforce color theme ('light', 'dark')
}, function(state) {
if (state == Brite.STATE_COMPLETED) {
console.log("Client completed");
}
}, function() {
client.stop();
});
5. Handling Brite Client Events with JavaScript Callbacks
The Brite Web SDK provides a powerful mechanism for you to monitor and react to key session events within the Brite Client using JavaScript callbacks. This real-time event handling enables you to tailor the user experience based on the progress of the session flow.
The Brite Client is rendered inside an iframe. It communicates with your application using the browser’s postMessage API. The SDK abstracts this communication and exposes a simple interface through the client.start() method.
client.start(options, onStateChangeCallback, onCloseCallback);
You provide callback functions to handle:
- State changes (e.g., user completed authentication, session failed, session completed)
- Client closure (e.g., user aborted the process, closed the iframe or completed the session)
|
Callback Argument
|
Triggered by
|
Description
|
|---|---|---|
|
stateCallback(state)
|
state event
|
Fires when the client changes state. Receives a constant (see full list of session state constants below).
|
|
Fires when the user exits or the session ends.
|
Events dispatched by the iframe
The embedded Brite Client dispatches structured message events to the parent window. These events include:
|
Event name
|
Description
|
|---|---|
|
load
|
Fired when the iframe finishes loading and becomes visible.
|
|
state
|
Sent whenever the client moves to a new state* (e.g., authentication started).
|
|
close
|
state event includes a numeric state value matching a Brite.STATE_* constant. See the full list of session state constants here.
//Usage Example: Responding to State Changes
const client = new Brite("your-brite-session-token");
client.start(
{
selector: "#BritePayment",
width: "400px",
height: "600px",
},
function(state) {
console.log("Brite Client state changed:", state);
switch (state) {
case Brite.STATE_AUTHENTICATION_COMPLETED: // Optional in Brite Play Flow
console.log("Authentication completed. Notifying backend to retrieve KYC data...");
try {
await fetch('/api/brite/session/verify', {
method: 'POST',
headers: {
'Content-Type': 'application/json'
},
body: JSON.stringify({ sessionId: currentSessionId })
});
} catch (error) {
console.error("Error starting backend verification:", error);
}
break;
case Brite.STATE_COMPLETED:
document.getElementById("payment-success-message").style.display = "block";
break;
case Brite.STATE_ABORTED:
case Brite.STATE_FAILED:
document.getElementById("payment-error-message").style.display = "block";
break;
default:
console.log("Unhandled state:", state);
}
},
function() {
console.log("Brite Client closed.");
client.stop(); // Remove iframe and clean up
}
);
6. Defining the Color Theme
Customizing the look and feel of the Client is simple with the color_theme parameter. By default, the Client uses a light theme. However, you can explicitly force a theme to match your brand.
Color Theme Options
light: Use this option for a light theme.dark: Use this option for a dark theme.auto: Use this option to set the theme depending on the user’s browser preferences.
// Example of Setting the Color Theme
client.start({
selector: '#BritePayment',
width: '400px',
height: '600px',
color_theme: 'dark' // Optional: Enforce color theme ('light', 'dark')
}, function(state) {
if (state === Brite.STATE_COMPLETED) {
console.log("Client completed");
}
}, function() {
client.stop();
});
7. Implementation Tips
Responsive Containers
Ensure your container dynamically adjusts using CSS Flexbox or Grid layouts. This prevents layout issues and enhances the viewing experience on various devices.Full-Viewport Mobile Experience
On mobile devices, always set the container to occupy the full viewport using100vwand100vh.Clean UI
Avoid adding UI elements (such as extra buttons or overlays) that could obstruct the Client. This is strictly forbidden to maintain usability.Event Logging and Monitoring
Use the state callbacks to log and respond to events for fine-tuning your user experience.
