Embedded Apps for Webex Devices Developer Guidelines
anchorIntroduction
anchorThis document provides design and experience guidelines for embedded apps running on Webex Devices. It provides the following levels of guidance:
Requirements that in-meeting embedded apps must meet to be approved for inclusion on Webex App Hub. IMPORTANT: Webex App Hub is not supported for Webex for Government (FedRAMP). Recommended design guidelines that when implemented provide a great experience for users. While not explicitly required, apps that do not incorporate the recommended guidelines may not be approved if it is determined they provide a poor user experience.Good-to-have design guidelines that when incorporated provide an enhanced user experience, both within the app itself and the larger Webex context.
Submit your idea for an embedded app on Webex Devices!
anchorAbout Webex Devices
anchorWebex video devices are purpose built for video conferencing and visual collaboration for effortless new ways to connect with your team, share your ideas, and express yourself. Webex devices are designed to provide high-quality meeting experiences without needing a laptop.
Cisco makes devices to meet the needs of today’s hybrid digital world: providing solutions for all types of meeting spaces, as well as home offices. As work is hybrid, employees need access to people, content and applications no matter where they conduct work. To help address those needs, applications can be embedded in Webex and now Webex Devices to enable rich collaboration. To learn more about Webex devices, please visit Project Workplace.
You use the Webex Embedded App SDK to create apps that run on Webex devices. This guide provides additional guidelines and requirements to consider when creating apps for Webex Devices. This document also provides unique requirements and limitations for embedded apps on Webex Devices.
anchorSupported Devices
anchor| Device | Description | More information | Data sheet link |
|---|---|---|---|
Webex Board Pro
| All-in-one touch device for video conferencing, digital whiteboarding and team collaboration in a meeting room. | Visit here | Board Pro |
Webex Board
| First generation Webex Board for an all-in-one meeting room experience. | See above for the all-new Board Pro. | |
Desk Pro
| All-in-one collaboration device for your desk or huddle room. | Visit here | Desk Pro |
Desk
| All-in-one collaboration device for every desk; at home or in the office. | Visit here | Desk |
Desk Mini
| A portable all-in-one desk device designed for taking meetings in any room. | Visit here | here |
anchorUser Experience on Webex Devices
anchorEmbedded Apps are available in Webex meetings and Webex spaces. Apps can currently only be shared (via Open Together or Add to Tab) from the desktop Webex app, but any supported device participating in the meeting will open the app whenever a session is initiated. Apps can be displayed in two views:
Panel view — This is the default view when an embedded app is opened or shared. The panel width is fixed.
Stage view — Users can expand the app to fill the stage.
The following buttons let users switch between the two views and close the embedded app.
| Go from panel view to stage view |  |
| Go from stage view to panel view |  |
| Close Embedded App (only locally) |  |
For in-meeting apps, if an app is closed it can be re-opened from the Apps button as long as the sharing session is still in progress.
anchorApp Submission and Approval
anchorOnly embedded apps that have approved for Webex AppHub can be used on Webex Devices. To have your app approved please start by reviewing the design requirements and recommendations in this document. If your app is suitable for Webex Devices and can work well within the technical requirements please submit your idea for consideration and we will get to back to you with next steps.
anchorOptimizing the Experience for Webex Devices
anchorEmbedded apps can check the value of webex.application.deviceType in the Embedded App SDK to see what type of device the application is running on. This property currently returns the string "ROOM_SYSTEM_PERSONAL" when running on a Webex Device. Information about the exact device model can be found in the webex.application.about property. This makes it possible to adapt the functionality of your app specifically for the Webex Device, if needed.
anchorTechnical Requirements and Limitations
anchorThis section describes design and development considerations unique to creating embedded apps for Webex Devices.
Testing and DebuggingUser Experience and NavigationHardwareUnsupported web featuresMultimedia
Testing and Debugging
Unlike on the Webex App for desktop systems, Webex Devices don't currently provide a way to enable developer tools inor the "Refresh" button to in the embedded webview to reload your app from its source URL.
To test changes you've deployed to your embedded app once you've started it on a Webex Device you need to manually restart the app. Webex will reload your app's updated assets from your web host.
User Experience and Navigation
Embedded apps on Webex devices can currently be used to only receive content shared by other meeting participants. In other words, embedded apps on Webex Devices cannot call setShareUrl() to share content with other meeting participants via the Open Together feature. All user interaction must be done through touch events.Using window.open() to open external browser windows is not supported.Browser history navigation (for example, "back" or "forward" buttons) are not available. However, apps can use the JavaScript History API to move forward or back in the user's navigation history.The device keyboard is only available for text input fields on the touch screen (no keyboard shortcuts).Webex Devices do not support the ability to "Refresh" (reload) the embedded app from it's original URL.
Hardware
The web engine used to render embedded apps on device is based on the Chromium/Qt WebEngine with V8 JavaScript. The current version is Chromium 77, with ongoing work to support Chromium 87.
Unsupported web features
The following web features are not supported by the Webex Devices web engine:
PDF renderingFile upload and downloadWebGLSession cookies
Multimedia
Audio and video playback is supported. It is recommended to limit video resolution to 1080p resolution to ensure smooth playback.
anchorRequirements for Embedded Apps on Devices
anchorThis section describes design and user experience requirements for in-meeting embedded apps.
Open Together ExperienceResponsive LayoutPlatform and Device SupportTouch Screen SupportScrolling AbilityAccess to User InformationFirst-time User ExperienceLegibility in Light and Dark ModesOther
Open Together Experience
Open Together is the heart of the in-meeting app experience. The following requirements are to ensure that an app's Open Together workflows are clear and intuitive to users.
Embedded apps on Webex Devices cannot initiate Open Together sessions in a Webex Meeting, they can only act as recipients of content shared by other meeting participants.
The following guidelines apply only to recipients of on Open Together session:
Apps must be optimized the app recipient who interacts with the opened app.While an Open Together session is in progress, app recipients must be presented with the same view or content that the app initiator intended to share. If the app recipient navigates away from the intended view, the app must provide a way for the user to return to the intended experience.
Responsive Layout
Apps must optimize their layouts to their default viewports. As detailed below, there are unique viewport sizes for apps running in the App panel (where apps open by default) and in full-screen mode that the user can enable.
App Panel
By default, apps are launched into the App panel with a fixed viewport. Apps must be optimized for this viewport. Users cannot resize the App panel.
Stage View
Users can tap the expand icon in the app's title bar to make the window fill the device's screen. Apps must adapt their layout responsively to this viewport.
Touch Screen Support
All user interaction on Webex Devices must be done through touch events. App must be optimized for a touch-screen experience.
Scrolling Ability
Apps must provide users with the ability to easily scroll the app's visible content. By default, in-meeting apps open in the App panel, which may contain other open panels (such as Chat or Participants panel, for example) thereby reducing the app's available screen area. For example, in the screenshot below the Slido app is open and is sharing the available space with other panels. Users must be able to access app content in this view by scrolling vertically.
Webex Device Support
Apps must be tested and verified to function as expected on all supported Webex Devices. See Supported Devices for links to data sheets providing screen size information for each device.
Access to User Information
Apps must not require a user to provide a phone number to enable use of the app. If the app solicits personal information from the user, it must not spam users with that information.Apps must not be dependent on access to a user's personally identifiable information (PII) to function properly. By default, access to PII in embedded apps is not enabled and apps must be able to function without access to PII. For more information, see Access to Personally Identifying Information.Embedded apps may obtain user information via an Integration with Webex APIs, but integrations should limit the requested scopes to the minimum their application needs to function. For more information, see Combined Webex Developer Solutions in the Embedded Apps Developer Guide.
First-time User Experience
The following are requirements for the first-time user experience.
Apps must be easy and intuitive for first-time users and provide clear call-to-actions (CTAs) in onboarding workflows.If a user is required to sign-in to use the app, all available sign-in methods in the app must be functional.If the user needs to first sign-up (create an external account) before using the app, the app must provide guidance on how users need to complete that process.
Other
If an app encounters an error condition that it cannot recover from, it must provide users with graceful exit points and appropriate messaging about the error state.Apps that require a user to sign-in must also provide a way for the user to sign-out.Apps must not display advertisements. This requirement is evaluated on a per-app basis and depends on the situation (for example, if an app's underlying business model is dependent on ads).Apps must not include links to extraneous pages where not actionable (for example, links to "About", "Careers", or social media sites) that would leave the user "stranded".
anchorRecommended Design Guidelines
anchorEmbedded apps are expected to follow the recommended design guidelines discussed below. While not required for approval, apps that do not incorporate these recommended guidelines may not be approved for App Hub if the reviewer determines that the app provides a poor user experience.
Except where noted, the recommended design guidelines apply to both in-meeting and in-space apps.
Open Together Experience RecommendationsFocus on Simplified Workflows and Use CasesRespond to User's Color Theme PreferenceSign-in Guidelines
Open Together Experience Recommendations
The following are recommendations for the Open Together experience:
Apps should avoid including hyperlinks to parts of the application that weren't intended to be part of the embedded app experience, or take the user to an unknown part of the app.If certain Open Together workflows are not enabled in the app, the developer should minimally provide the user with next steps through a text banner.
Focus on Simplified Workflows and Use Cases
Developers should not try to repurpose or replicate their entire existing web app as an embedded app. Embedded apps benefit users with simplified use cases and workflows that add value to a Webex meeting or messaging space.
Respond to User's Color Theme Preference
Webex users can select a light or dark theme for the Webex or Meeting Center app. To provide the best user experience, embedded apps should be responsive to the user's theme preference and provide both light and dark color themes. Minimally, an app's light theme should provide dark-colored text on a light-colored background, while the dark them should display light-colored text on a dark-colored background.
Sign-in Guidelines
Apps that require user accounts should make the sign-up and sign-in processes as easy as possible for the user. Specifically, apps should incorporate the following:
App recipients should have the same or similar sign-up and sign-in experience as the app initiator.Apps should use cookies and local storage to persist a user's log-in information, so that users do not need to log in each time they open a space tab or join an Open Together session. The embedded app version of your service or application should provide the same sign-in or session persistence as the browser-based version. See Using Cookies and Web Storage in the Embedded Apps developer guide for more information.Apps should use third-party identity providers for user sign-in only when necessary.
anchorGood-to-Have Design Guidelines
anchorThe following suggestions provide an enhanced user experience both within your app and in the larger Webex context. Incorporating these suggestions is optional and will not block app approval if not implemented.
Provide a "Freemium" Model for First-time Users
Apps that require users to create an account and select a pricing plan should provide a "freemium" model to allow first-time users an easy sign-up experience. Apps can use the participant's user ID to create a placeholder association between the user and the current app session. This ID is guaranteed to be unique regardless of whether the app has access to the user's personally identifiable information (PII).