1"use strict";(globalThis.webpackChunkbambuser_docs||=[]).push([[3274],{35207(e,n,s){s.r(n),s.d(n,{assets:()=>c,contentTitle:()=>l,default:()=>h,frontMatter:()=>t,metadata:()=>r,toc:()=>d});const r=JSON.parse('{"id":"api-screen","title":"Screen API","description":"Screen API reference: screenApi.createScreen, provide-instance event for custom screens in Live Player (showsPlayer) and Calls Widget, screen view messaging.","source":"@site/app-framework/buildApiScreen.mdx","sourceDirName":".","slug":"/build/api/screen","permalink":"/docs/app-framework/build/api/screen","draft":false,"unlisted":false,"tags":[],"version":"current","frontMatter":{"id":"api-screen","title":"Screen API","description":"Screen API reference: screenApi.createScreen, provide-instance event for custom screens in Live Player (showsPlayer) and Calls Widget, screen view messaging.","sidebar_label":"Screen","slug":"build/api/screen"},"sidebar":"someSidebars","previous":{"title":"Dialogs","permalink":"/docs/app-framework/learn/ui/dialogs"},"next":{"title":"Tool","permalink":"/docs/app-framework/build/api/tool"}}');var i=s(74848),a=s(28453);const t={id:"api-screen",title:"Screen API",description:"Screen API reference: screenApi.createScreen, provide-instance event for custom screens in Live Player (showsPlayer) and Calls Widget, screen view messaging.",sidebar_label:"Screen",slug:"build/api/screen"},l=void 0,c={},d=[{value:"Registration in App manifest",id:"registration-in-app-manifest",level:2},{value:"Methods",id:"methods",level:2},{value:"createScreen()",id:"createscreen",level:3},{value:"Parameters",id:"parameters",level:4},{value:"Return value",id:"return-value",level:4},{value:"Example",id:"example",level:4},{value:"Events",id:"events",level:2},{value:"provide-instance",id:"provide-instance",level:3},{value:"Event properties",id:"event-properties",level:4},{value:"Event return value",id:"event-return-value",level:4},{value:"Example",id:"example-1",level:4},{value:"Screen view",id:"screen-view",level:2},{value:"Screen view methods",id:"screen-view-methods",level:2},{value:"setReady()",id:"setready",level:3},{value:"Return value",id:"return-value-1",level:4},{value:"Example",id:"example-2",level:4},{value:"close()",id:"close",level:3},{value:"Parameters",id:"parameters-1",level:4},{value:"Return value",id:"return-value-2",level:4},{value:"Example",id:"example-3",level:4},{value:"emit()",id:"emit",level:3},{value:"Parameters",id:"parameters-2",level:4},{value:"Return value",id:"return-value-3",level:4},{value:"Example",id:"example-4",level:4},{value:"postMessage()",id:"postmessage",level:3},{value:"Parameters",id:"parameters-3",level:4},{value:"Return value",id:"return-value-4",level:4},{value:"Example",id:"example-5",level:4},{value:"Screen view events",id:"screen-view-events",level:2},{value:"open",id:"open",level:3},{value:"Example",id:"example-6",level:4},{value:"close",id:"close-1",level:3},{value:"Example",id:"example-7",level:4},{value:"message",id:"message",level:3},{value:"Event properties",id:"event-properties-1",level:4},{value:"Example",id:"example-8",level:4}];function o(e){const n={a:"a",admonition:"admonition",br:"br",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.R)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsxs)(n.p,{children:["Bambuser product: ",(0,i.jsx)(n.code,{children:"Live"})," / ",(0,i.jsx)(n.code,{children:"Video Consultation"})]}),"\n",(0,i.jsxs)(n.p,{children:["An API to provide custom User Interface ",(0,i.jsx)(n.a,{href:"/app-framework/learn/ui/screens",children:"Screens"})," from your app"]}),"\n",(0,i.jsx)(n.h2,{id:"registration-in-app-manifest",children:"Registration in App manifest"}),"\n",(0,i.jsxs)(n.p,{children:["The app must registered each screen it would like to provide in ",(0,i.jsx)(n.strong,{children:"App manifest"})," using the ",(0,i.jsx)(n.code,{children:"{hostId}.screens"})," property, see User Interface ",(0,i.jsx)(n.a,{href:"/app-framework/learn/ui/screens#slots",children:"Screens"})," for the available slots a screen can be put into"]}),"\n",(0,i.jsxs)("blockquote",{children:[(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Example screen registration in App manifest:"})}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-json",metastring:"{145}",children:'{\n "permissions": [\n "callsWidget:screen.write"\n ],\n "url": {\n "type": "module",\n "src": "http://your-app-domain.com/main.js"\n },\n "callsWidget": {\n "screens": [{\n "id": "my-custom-screen",\n "slot": "drop-in"\n }]\n }\n}\n'})})]}),"\n",(0,i.jsx)(n.h2,{id:"methods",children:"Methods"}),"\n",(0,i.jsx)(n.h3,{id:"createscreen",children:"createScreen()"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," ",(0,i.jsx)(n.code,{children:"callsWidget:screen.write"})," / ",(0,i.jsx)(n.code,{children:"showsPlayer:screen.write"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app"]}),"\n",(0,i.jsxs)(n.p,{children:["Create a custom screen with the view provided by your app. This API should be used in conjunction with the ",(0,i.jsx)(n.a,{href:"#provide-instance",children:(0,i.jsx)(n.code,{children:"provide-instance"})})," event"]}),"\n",(0,i.jsx)(n.h4,{id:"parameters",children:"Parameters"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"id"})," - String for the id associated with the screen"]}),"\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"viewUrl"})," - Url to the screens's view, must have the same origin as the URL to your app's main entrypoint"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"return-value",children:"Return value"}),"\n",(0,i.jsxs)(n.p,{children:["A promise whose fulfillment handler will receive an instance of a ",(0,i.jsx)(n.a,{href:"#screen-view",children:"Screen view"}),"."]}),"\n",(0,i.jsx)(n.h4,{id:"example",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"const { screenApi } = await bambuserAppFramework.getContext();\n\nconst screen = await screenApi.createScreen({\n id: 'my-custom-screen',\n viewUrl: 'http://your-app-domain.com/custom-screen.html',\n});\n"})}),"\n",(0,i.jsx)(n.h2,{id:"events",children:"Events"}),"\n",(0,i.jsx)(n.h3,{id:"provide-instance",children:"provide-instance"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," ",(0,i.jsx)(n.code,{children:"callsWidget:screen.write"})," / ",(0,i.jsx)(n.code,{children:"showsPlayer:screen.write"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app"]}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsx)(n.h4,{id:"event-properties",children:"Event properties"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"id"})," - The id corresponding to the screen registration in App manifest that should be provided"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"event-return-value",children:"Event return value"}),"\n",(0,i.jsxs)(n.p,{children:["It is expected that the event handler will return a screen view created by ",(0,i.jsx)(n.a,{href:"#createscreen",children:(0,i.jsx)(n.code,{children:"createScreen()"})})," with the id provided by the event"]}),"\n",(0,i.jsx)(n.h4,{id:"example-1",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-javascript",metastring:"{145}",children:"const { screenApi } = await bambuserAppFramework.getContext();\n\nscreenApi.on('provide-instance', async ({ id }) =>
1 {\n const screen = await screenApi.createScreen({\n id, // Must match the requested id, corresponds to the id for the screen added in App Manifest\n viewUrl: `http://your-app-domain.com/custom-screens/${id}.html`,\n });\n\n screen.on('close', event => {\n console.log(`Screen ${id} was closed`, event);\n });\n\n return screen;\n});\n"})}),"\n",(0,i.jsx)(n.h2,{id:"screen-view",children:"Screen view"}),"\n",(0,i.jsx)(n.p,{children:"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 being the only view that is presented to the user within the Bambuser product."}),"\n",(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.a,{href:"#emit",children:(0,i.jsx)(n.code,{children:"emit()"})})," / ",(0,i.jsx)(n.a,{href:"#postmessage",children:(0,i.jsx)(n.code,{children:"postMessage()"})})," / ",(0,i.jsx)(n.a,{href:"#message",children:(0,i.jsx)(n.code,{children:"message"})})]}),"\n",(0,i.jsxs)("blockquote",{children:[(0,i.jsx)(n.p,{children:(0,i.jsx)(n.strong,{children:"Example screen view:"})}),(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-html",metastring:"{145}",children:'<!DOCTYPE html>\n<html lang="en" className="bam-ui">\n <head>\n <meta charset="UTF-8">\n <meta name="viewport" content="width=device-width, initial-scale=1.0">\n <meta http-equiv="X-UA-Compatible" content="ie=edge">\n <title>Custom screen</title>\n <link rel="stylesheet" href="https://app-framework.bambuser.com/bam-ui.css" />\n </head>\n <body>\n <h1>Hello world</h1>\n <script src="https://app-framework.bambuser.com/runtime.js"><\/script>\n <script src="https://app-framework.bambuser.com/bam-ui.js"><\/script>\n <script type="module">\n const { screen } = await bambuserAppFramework.getContext();\n screen.setReady();\n <\/script>\n </body>\n</html>\n'})})]}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsxs)(n.p,{children:["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 ",(0,i.jsx)(n.a,{href:"#setready",children:(0,i.jsx)(n.code,{children:"setReady()"})}),". Until you do this, a loader will be shown to the user"]})}),"\n",(0,i.jsx)(n.admonition,{type:"info",children:(0,i.jsx)(n.p,{children:"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"})}),"\n",(0,i.jsx)(n.h2,{id:"screen-view-methods",children:"Screen view methods"}),"\n",(0,i.jsx)(n.h3,{id:"setready",children:"setReady()"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Screen view"]}),"\n",(0,i.jsx)(n.p,{children:"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."}),"\n",(0,i.jsx)(n.h4,{id:"return-value-1",children:"Return value"}),"\n",(0,i.jsx)(n.p,{children:"None."}),"\n",(0,i.jsx)(n.h4,{id:"example-2",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"const { screen } = await bambuserAppFramework.getContext();\n\n// All necessary resources has been loaded and the UI is presentable to the user\n// The loader currently showing should be removed and the screen UI presented\nscreen.setReady();\n"})}),"\n",(0,i.jsx)(n.h3,{id:"close",children:"close()"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Screen view"]}),"\n",(0,i.jsx)(n.p,{children:"Close the screen and pass user further in the user flow with an action deciding what should happen"}),"\n",(0,i.jsx)(n.h4,{id:"parameters-1",children:"Parameters"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"action"})," - The screen close action, available actions are:","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:'"next"'})," - Pass user further, to the next screen in the current user flow"]}),"\n",(0,i.jsxs)(n.li,{children:["Calls Widget:","\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:'"book"'})," - Switch user flow, to ",(0,i.jsx)(n.strong,{children:"booking flow"})," where the user is able to schedule a call for some time later"]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"return-value-2",children:"Return value"}),"\n",(0,i.jsx)(n.p,{children:"None."}),"\n",(0,i.jsx)(n.h4,{id:"example-3",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"const { screen } = await bambuserAppFramework.getContext();\n\n// ...\n\nscreen.close({ action: 'next' });\n"})}),"\n",(0,i.jsx)(n.h3,{id:"emit",children:"emit()"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Screen view"]}),"\n",(0,i.jsx)(n.p,{children:"Send a message from screen view context to main app context"}),"\n",(0,i.jsx)(n.h4,{id:"parameters-2",children:"Parameters"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"payload"})," - The message payload to send to the main app context"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"return-value-3",children:"Return value"}),"\n",(0,i.jsx)(n.p,{children:"None."}),"\n",(0,i.jsx)(n.h4,{id:"example-4",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"const { screen } = await bambuserAppFramework.getContext();\n\n// ...\n\nscreen.emit({\n eventName: 'hello-from-screen-view-context',\n data: {\n foo: 'bar',\n },\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"postmessage",children:"postMessage()"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app"]}),"\n",(0,i.jsx)(n.p,{children:"Send a message from main app context to screen view context"}),"\n",(0,i.jsx)(n.h4,{id:"parameters-3",children:"Parameters"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"payload"})," - The message payload to send to the screen view context"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"return-value-4",children:"Return value"}),"\n",(0,i.jsx)(n.p,{children:"None."}),"\n",(0,i.jsx)(n.h4,{id:"example-5",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"// ...\n\nscreen.postMessage({\n eventName: 'hello-from-main-context',\n data: {\n foo: 'bar',\n },\n});\n"})}),"\n",(0,i.jsx)(n.h2,{id:"screen-view-events",children:"Screen view events"}),"\n",(0,i.jsx)(n.h3,{id:"open",children:"open"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app"]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"open"})," event is fired in main app context when screen is opened"]}),"\n",(0,i.jsx)(n.h4,{id:"example-6",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"// ...\n\nscreen.on('open', () => {\n console.log('Screen was opened');\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"close-1",children:"close"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app"]}),"\n",(0,i.jsxs)(n.p,{children:["The ",(0,i.jsx)(n.code,{children:"close"})," event is fired in main app context when screen is closed"]}),"\n",(0,i.jsx)(n.h4,{id:"example-7",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"// ...\n\nscreen.on('close', () => {\n console.log('Screen was closed');\n});\n"})}),"\n",(0,i.jsx)(n.h3,{id:"message",children:"message"}),"\n",(0,i.jsxs)(n.p,{children:[(0,i.jsx)(n.strong,{children:"Permission:"})," Implicit via ",(0,i.jsx)(n.a,{href:"/app-framework/build/api/screen#createscreen",children:"Screen API"}),(0,i.jsx)(n.br,{}),"\n",(0,i.jsx)(n.strong,{children:"Context:"})," Main app, Screen view"]}),"\n",(0,i.jsx)(n.p,{children:"Receive a message sent from the main app context or screen view context"}),"\n",(0,i.jsx)(n.h4,{id:"event-properties-1",children:"Event properties"}),"\n",(0,i.jsxs)(n.ul,{children:["\n",(0,i.jsxs)(n.li,{children:[(0,i.jsx)(n.code,{children:"event.*"})," - The message payload sent from other context"]}),"\n"]}),"\n",(0,i.jsx)(n.h4,{id:"example-8",children:"Example"}),"\n",(0,i.jsx)(n.pre,{children:(0,i.jsx)(n.code,{className:"language-jsx",children:"// ...\n\nscreen.on('message', event => {\n console.log('Screen message event', event);\n});\n"})})]})}function h(e={}){const{wrapper:n}={...(0,a.R)(),...e.components};return n?(0,i.jsx)(n,{...e,children:(0,i.jsx)(o,{...e})}):o(e)}},28453(e,n,s){s.d(n,{R:()=>t,x:()=>l});var r=s(96540);const i={},a=r.createContext(i);function t(e){const n=r.useContext(a);return r.useMemo(function(){return"function"==typeof e?e(n):{...n,...e}},[n,e])}function l(e){let n;return n=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:t(e.components),r.createElement(a.Provider,{value:n},e.children)}}}]);
Line numbers count LF bytes from the start of the resource, as the search results do. Vendor segments are library code the classifier recognised; they are stored but not indexed. Bytes are shown as Latin1 characters, one per byte.