Search
Menu
Edit Template

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 */
  }
}
				
			
Mobile Devices: The Brite Client is required to occupy the full viewport to enhance the user experience.
				
					/* 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>
				
			
Define the Brite Client using the Brite JavaScript SDK, initializing it with the session_token obtained from the session creation step.

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
* Each 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 using 100vw and 100vh.

  • 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.