Embed SDK Reference

Including Kota.js

Include the Kota.js script on each page you want to run it on - it should always be loaded directly from https://js.kota.io or https://test.js.kota.io, rather than included in a bundle or hosted yourself. This ensures compliance and future updates.

When you are ready to go-live make sure your production environment is not including the test SDK.

Including Kota.js for testing
1<script src="https://test.js.kota.io/v1"></script>
Including Kota.js for production
1<script src="https://js.kota.io/v1"></script>

Initialising Kota.js

Employer

Kota.Health.employer(employerAccessToken, options?)

Use Kota.Health.Employer(employerAccessToken, options?) to create an instance of the Kota Health’s Employer embedded UI.

The employerAccessToken can be retrieved from the Embed Session endpoint.

Once initialised, if the optional container has not been provided, the employer embed will load in on a <div> with id="employer".

Method parameters

employerAccessTokenstringRequired
Token retrieved from the /embed/session endpoint to authenticate the user session.
options
objectOptional
container
stringOptional
The id of the container to load the Embedded UI in.
Default value: employer
theme
objectOptional
dependants_cover
enumOptional
Configure employer’s options for covering dependants. Full allows employers to choose covering spouse & children separately, binary restricts employer cover to all dependants or none, and none doesn’t allow the employer to cover their employees’ dependants. Default value: full
Allowed values: fullbinarynone
1const employerEmbed = Kota.Health.employer();
2
3const themeConfig = {
4  primaryColor: '#0875E1',
5  backgroundColor: '#fff',
6  radius: '12px',
7  ringColor: '#0875E1'
8};
9
10employerEmbed.init(
11  employerAccessToken,
12  { container: 'employer', theme: themeConfig }
13);

Employee

Kota.Health.employee(employeeAccessToken, options?)

Use Kota.Health.Employee(employeeAccessToken, options?) to create an instance of the Kota Health’s Employee embedded UI.

The employeeAccessToken can be retrieved from the Embed Session endpoint.

Once initialised, if the optional container has not been provided, the employer embedded will load in on a <div> with id="employee".

Method parameters

employeeAccessTokenstringRequired
Token retrieved from the /embed/session endpoint to authenticate the user session.
options
objectOptional
container
stringOptional
The id of the container to load the Embedded UI in.
Default value: employee
theme
objectOptional
1const employeeEmbed = Kota.Health.employee();
2
3const themeConfig = {
4  primaryColor: '#0875E1',
5  backgroundColor: '#fff',
6  radius: '12px',
7  ringColor: '#0875E1'
8};
9
10employeeEmbed.init(
11  employeeAccessToken,
12  { container: 'employee', theme: themeConfig }
13);

Browser events

The only way to communicate with your Embedded UI in the browser is by listening to an event.

You can set up listeners directly from your initialised employer and employee objects or by directly listening for the events on the window.

1// events can be called on this object
2const employerEmbed = Kota.Health.employer();
3employerEmbed.init(employeeAccessToken);
4
5function handler(event) {
6  // Handle any metrics or actions here
7}
8
9employerEmbed.on('eventName', handler);
BROWSER EVENT LIST
Event nameDescription
employer.pageLoadedFires when a new page loads. Object contains page title.
employer.healthSetupLoadedFires when the employer health insurance setup flow loads.
employer.healthManagementLoadedFires when the employer health insurance setup management loads.
employer.loadErrorFires when the employer embedded UI fails to load.
employee.pageLoadedFires when a new page loads. Object contains page title.
employee.healthSetupLoadedFires when the employee health insurance setup flow loads.
employee.healthManagementLoadedFires when the employee health insurance setup management loads.
employee.loadErrorFires when the employee embedded UI fails to load.

pageLoaded

The pageLoaded event fires each time a new page is loaded throughout an Embedded UI - both for employer and employee.

You can listen for it directly from your initialised objects, e.g. employerEmbed.on('pageLoaded', handler), or with event listeners. If listeningly directly be careful to listen for the correct event as they are namespaced by employer and employee - see the event list for more information.

Method parameters

event”pageLoaded”Required
The name of the event. See code examples for the embedded object and window listeners.
handler
functionRequired
handler(event) => void is a callback function that you provide that will be called when the event is fired.
After it’s called, it passes an event object with the following properties:
pageTitle
string
The title of the page loaded in the Embedded UI.
1employerEmbed.on('pageLoaded', function(event) {
2  // Handle employer pageLoaded event
3})

healthSetupLoaded

The healthSetupLoaded event fires each time a new page is loaded throughout an Embedded UI - both for employer and employee.

You can listen for it directly from your initialised objects, e.g. employerEmbed.on('healthSetupLoaded', handler), or with event listeners. If listeningly directly be careful to listen for the correct event as they are namespaced by employer and employee - see the event list for more information.

Method parameters

event”healthSetupLoaded”Required
The name of the event. See code examples for the embedded object and window listeners.
handler
functionRequired
handler(event) => void is a callback function that you provide that will be called when the event is fired.
1employerEmbed.on('healthSetupLoaded', function(event) {
2  // Handle employer pageLoaded event
3})

healthManagementLoaded

The healthManagementLoaded event fires each time a new page is loaded throughout an Embedded UI - both for employer and employee.

You can listen for it directly from your initialised objects, e.g. employerEmbed.on('healthManagementLoaded', handler), or with event listeners. If listeningly directly be careful to listen for the correct event as they are namespaced by employer and employee - see the event list below for more information.

Method parameters

event”healthManagementLoaded”Required
The name of the event. See code examples for the embedded object and window listeners.
handler
functionRequired
handler(event) => void is a callback function that you provide that will be called when the event is fired.
1employerEmbed.on('healthManagementLoaded', function(event) {
2  // Handle employer pageLoaded event
3})

loadError

The loadError event fires when the Embedded UI fails to load.

You can listen for it directly from your initialised objects, e.g. employerEmbed.on('loadError', handler), or with event listeners. If listeningly directly be careful to listen for the correct event as they are namespaced by employer and employee - see the event list below for more information.

Method parameters

event”loadError”Required
The name of the event. See code examples for the embedded object and window listeners.
handler
functionRequired
handler(event) => void is a callback function that you provide that will be called when the event is fired.
1employerEmbed.on('loadError', function(event) {
2  // Handle employer loadError event
3})