Screen API
Bambuser product: One-to-Many / One-to-One
An API to provide custom User Interface Screens from your app
Registration in App manifest
The app must registered each screen it would like to provide in App manifest using the {hostId}.screens property, see User Interface Screens for the available slots a screen can be put into
Example screen registration in App manifest:
{
"permissions": [
"callsWidget:screen.write"
],
"url": {
"type": "module",
"src": "http://your-app-domain.com/main.js"
},
"callsWidget": {
"screens": [{
"id": "my-custom-screen",
"slot": "drop-in"
}]
}
}
Methods
createScreen()
Permission: callsWidget:screen.write / showsPlayer:screen.write
Context: Main app
Create a custom screen with the view provided by your app. This API should be used in conjunction with the provide-instance event
Parameters
id- String for the id associated with the screenviewUrl- Url to the screens's view, must have the same origin as the URL to your app's main entrypoint
Return value
A promise whose fulfillment handler will receive an instance of a Screen view.
Example
const { screenApi } = await bambuserAppFramework.getContext();
const screen = await screenApi.createScreen({
id: 'my-custom-screen',
viewUrl: 'http://your-app-domain.com/custom-screen.html',
});
Events
provide-instance
Permission: callsWidget:screen.write / showsPlayer:screen.write
Context: Main app
When the user navigates to a slot associated with a screen provided by the app the actual screen view needs to be determined so the correct view may be shown.
Event properties
id- The id corresponding to the screen registration in App manifest that should be provided
Event return value
It is expected that the event handler will return a screen view created by createScreen() with the id provided by the event
Example
const { screenApi } = await bambuserAppFramework.getContext();
screenApi.on('provide-instance', async ({ id }) => {
const screen = await screenApi.createScreen({
id, // Must match the requested id, corresponds to the id for the screen added in App Manifest
viewUrl: `http://your-app-domain.com/custom-screens/${id}.html`,
});
screen.on('close', event => {
console.log(`Screen ${id} was closed`, event);
});
return screen;
});
Screen view
A screen view instance represents a specific screen that may be shown to the user. Its built as a normal HTML page and shown inside an iframe beeing the only view that is presented to the user within the Bambuser product.
As a screen runs in a separate context, referred to as the screen view context, communication between screen view context and main app context can be achieved with a bi-directional message channel, see emit() / postMessage() / message
Example screen view:
<!DOCTYPE html>
<html lang="en" class="bam-ui">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta http-equiv="X-UA-Compatible" content="ie=edge">
<title>Custom screen</title>
<link rel="stylesheet" href="https://app-framework.bambuser.com/bam-ui.css" />
</head>
<body>
<h1>Hello world</h1>
<script src="https://app-framework.bambuser.com/runtime.js"></script>
<script src="https://app-framework.bambuser.com/bam-ui.js"></script>
<script type="module">
const { screen } = await bambuserAppFramework.getContext();
screen.setReady();
</script>
</body>
</html>
The page loaded in the screen iframe must load the Bambuser App Framework Runtime and communicate back when the UI is ready to be presented to the user by using setReady(). Until you do this, a loader will be shown to the user
The page loaded in the screen iframe must follow our Design Guidelines and make the look and feel to be aligned with other parts of the user interface
Screen view methods
setReady()
Permission: Implicit via Screen API
Context: Screen view
Decide when the screen is ready to be displayed, ex. your page has loaded completely and initial UI can be presented to the user. Before this, a loader will be displayed to the user.
Return value
None.
Example
const { screen } = await bambuserAppFramework.getContext();
// All necessary resources has been loaded and the UI is presentable to the user
// The loader currently showing should be removed and the screen UI presented
screen.setReady();
close()
Permission: Implicit via Screen API
Context: Screen view
Close the screen and pass user futher in the user flow with an action deciding what should happen
Parameters
action- The screen close action, available actions are:"next"- Pass user futher, to the next screen in the current user flow- One-to-One Call Widget:
"book"- Switch user flow, to booking flow where the user is able to schedule a call for some time later
Return value
None.
Example
const { screen } = await bambuserAppFramework.getContext();
// ...
screen.close({ action: 'next' });
emit()
Permission: Implicit via Screen API
Context: Screen view
Send a message from screen view context to main app context
Parameters
payload- The message payload to send to the main app context
Return value
None.
Example
const { screen } = await bambuserAppFramework.getContext();
// ...
screen.emit({
eventName: 'hello-from-screen-view-context',
data: {
foo: 'bar',
},
});
postMessage()
Permission: Implicit via Screen API
Context: Main app
Send a message from main app context to screen view context
Parameters
payload- The message payload to send to the screen view context
Return value
None.
Example
// ...
screen.postMessage({
eventName: 'hello-from-main-context',
data: {
foo: 'bar',
},
});
Screen view events
open
Permission: Implicit via Screen API
Context: Main app
The open event is fired in main app context when screen is opened
Example
// ...
screen.on('open', () => {
console.log('Screen was opened');
});
close
Permission: Implicit via Screen API
Context: Main app
The close event is fired in main app context when screen is closed
Example
// ...
screen.on('close', () => {
console.log('Screen was closed');
});
message
Permission: Implicit via Screen API
Context: Main app, Screen view
Receive a message sent from the main app context or screen view context
Event properties
event.*- The message payload sent from other context
Example
// ...
screen.on('message', event => {
console.log('Screen message event', event);
});