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

Allows you to customise the look and feel of the embedded UI to match your platform. Learn about theming your embedded UI here.

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

1 const employerEmbed = Kota.Health.employer();
2 
3 const themeConfig = {
4   primaryColor: '#0875E1',
5   backgroundColor: '#fff',
6   radius: '12px',
7   ringColor: '#0875E1'
8 };
9 
10 employerEmbed.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

Allows you to customise the look and feel of the embedded UI to match your platform. Learn about theming your embedded UI here.

1 const employeeEmbed = Kota.Health.employee();
2 
3 const themeConfig = {
4   primaryColor: '#0875E1',
5   backgroundColor: '#fff',
6   radius: '12px',
7   ringColor: '#0875E1'
8 };
9 
10 employeeEmbed.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
2 const employerEmbed = Kota.Health.employer();
3 employerEmbed.init(employeeAccessToken);
4 
5 function handler(event) {
6   // Handle any metrics or actions here
7 }
8 
9 employerEmbed.on('eventName', handler);

BROWSER EVENT LIST
Event name	Description
employer.pageLoaded	Fires when a new page loads. Object contains page title.
employer.healthSetupLoaded	Fires when the employer health insurance setup flow loads.
employer.healthManagementLoaded	Fires when the employer health insurance setup management loads.
employer.loadError	Fires when the employer embedded UI fails to load.
employee.pageLoaded	Fires when a new page loads. Object contains page title.
employee.healthSetupLoaded	Fires when the employee health insurance setup flow loads.
employee.healthManagementLoaded	Fires when the employee health insurance setup management loads.
employee.loadError	Fires 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.

1 employerEmbed.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.

1 employerEmbed.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.

1 employerEmbed.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.

1 employerEmbed.on('loadError', function(event) {
2   // Handle employer loadError event
3 })

Including Kota.js

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

Allows you to customise the look and feel of the embedded UI to match your platform. Learn about theming your embedded UI here.

dependants_cover

enumOptional

Allowed values: fullbinarynone

1 const employerEmbed = Kota.Health.employer();
2 
3 const themeConfig = {
4   primaryColor: '#0875E1',
5   backgroundColor: '#fff',
6   radius: '12px',
7   ringColor: '#0875E1'
8 };
9 
10 employerEmbed.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

Allows you to customise the look and feel of the embedded UI to match your platform. Learn about theming your embedded UI here.

1 const employeeEmbed = Kota.Health.employee();
2 
3 const themeConfig = {
4   primaryColor: '#0875E1',
5   backgroundColor: '#fff',
6   radius: '12px',
7   ringColor: '#0875E1'
8 };
9 
10 employeeEmbed.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
2 const employerEmbed = Kota.Health.employer();
3 employerEmbed.init(employeeAccessToken);
4 
5 function handler(event) {
6   // Handle any metrics or actions here
7 }
8 
9 employerEmbed.on('eventName', handler);

BROWSER EVENT LIST
Event name	Description
employer.pageLoaded	Fires when a new page loads. Object contains page title.
employer.healthSetupLoaded	Fires when the employer health insurance setup flow loads.
employer.healthManagementLoaded	Fires when the employer health insurance setup management loads.
employer.loadError	Fires when the employer embedded UI fails to load.
employee.pageLoaded	Fires when a new page loads. Object contains page title.
employee.healthSetupLoaded	Fires when the employee health insurance setup flow loads.
employee.healthManagementLoaded	Fires when the employee health insurance setup management loads.
employee.loadError	Fires 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.

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.

1 employerEmbed.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.

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.

1 employerEmbed.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.

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.

1 employerEmbed.on('healthManagementLoaded', function(event) {
2   // Handle employer pageLoaded event
3 })

loadError

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

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.

1 employerEmbed.on('loadError', function(event) {
2   // Handle employer loadError event
3 })

1	// events can be called on this object
2	const employerEmbed = Kota.Health.employer();
3	employerEmbed.init(employeeAccessToken);
4
5	function handler(event) {
6	// Handle any metrics or actions here
7	}
8
9	employerEmbed.on('eventName', handler);

1	employerEmbed.on('pageLoaded', function(event) {
2	// Handle employer pageLoaded event
3	})

1	employerEmbed.on('healthSetupLoaded', function(event) {
2	// Handle employer pageLoaded event
3	})

1	employerEmbed.on('healthManagementLoaded', function(event) {
2	// Handle employer pageLoaded event
3	})

1	employerEmbed.on('loadError', function(event) {
2	// Handle employer loadError event
3	})