Embedded Apps Reference
anchorBasic Usage
anchorTo add the Embedded Apps Framework to your web application add the following to the <HEAD>
of your app's main HTML page:
<script src="https://binaries.webex.com/static-content-pipeline/webex-embedded-app/v1/webex-embedded-app-sdk.js" defer></script>
In your app's main index.js file create a new Webex.Application
instance and create a function to handle the onReady()
promise when it resolves successfully.
var app = new window.Webex.Application();
app.onReady().then(function () {
console.log('App is ready. App info:', app);
});
anchorClasses
anchor- Webex.Application
Main application object you use to set sharing URLs, register event listeners, and get information about the application and its context.
Example usage
var app = new window.Webex.Application();
app.onReady().then(() => { // Create event listeners app.listen() .then(() => { app.on("application:shareStateChanged", (event) => { // Call custom function handleShareStateChange(event); }) app.on("application:themeChanged", (event) => { // Call custom function handleThemeChange(event); }) });
- Webex.Application.Context
Application context object that exposes methods for getting information about users, meetings, and spaces. It is exposed as a
context
property on the Webex Application instance.Example usage
var app = new window.Webex.Application();
app.onReady().then(() => { app.context.getUser().then((user) => { console.log("getUser() promise resolved. User", user); } ).catch((error) => { console.log("getUser() promise failed " + error.message); }) });
Webex.Application
Main application object you use to set sharing URLs, register event listeners, and get information about the application and its context.
Example usage
var app = new window.Webex.Application();
app.onReady().then(() => {
// Create event listeners
app.listen()
.then(() => {
app.on("application:shareStateChanged", (event) => {
// Call custom function
handleShareStateChange(event);
})
app.on("application:themeChanged", (event) => {
// Call custom function
handleThemeChange(event);
})
});
- Webex.Application
- webex.Application.deviceType :
string
- webex.Application.isPrivateDataAvailable :
boolean
- webex.Application.displayContext :
string
- webex.Application.isShared :
boolean
- webex.Application.capabilities :
Array.<string>
- webex.Application.sdkVersion :
string
- webex.Application.theme :
string
- webex.Application.about :
string
- webex.Application.language :
string
- webex.Application.setShareUrl(internalUrl, externalUrl, title, optionals) ⇒
Promise.<number>
- webex.Application.clearShareUrl()
- webex.Application.on(eventName, callback)
- webex.Application.off(eventName)
- webex.Application.listen() ⇒
Promise.<void>
- webex.Application.stopListening()
- webex.Application.onReady() ⇒
Promise.<void>
- Webex.Application.ErrorCodes
webex.Application.deviceType : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- deviceType - The given device form factor. One of [DESKTOP | MOBILE | BROWSER].
webex.Application.isPrivateDataAvailable : boolean
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- isPrivateDataAvailable - Indicates if real IDs for users, meetings, and spaces are available to the application (
true
), or if derived IDs are available (false
) . See About Access to Private Data in Embedded Apps for more information.
webex.Application.displayContext : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- displayContext - Display context in which the embedded app is running. One of the following strings: "MEETING_SIDEBAR", "MEETING_STANDALONE_WINDOW", "MEETING_MAINVIEW", or "SPACETAB". Default is "MEETING_SIDEBAR".
webex.Application.isShared : boolean
TRUE = share is ongoing; FALSE = share is not taking place.
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- isShared - Indicates if the embedded app’s link (specified using the app.setShareUrl() method) has been added to the meeting or space by the user.
webex.Application.capabilities : Array.<string>
A combination of TOUCH, SHARED_SYSTEM, MULTIPLE_USER_SYSTEM, and VIEW_ONLY.
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- capabilities - Indicates the capabilities of the given device. Currently not in use and subject to change. An empty string array is returned.
webex.Application.sdkVersion : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- sdkVersion - Indicates the SDK version the given meetings client implements. Example values: "1.x" for 41.6 to 41.9.
webex.Application.theme : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- theme - Indicates the given theme of the given meetings client, either Theme.LIGHT, or Theme.DARK.
webex.Application.about : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- about - General information about the host. This format is subject to change and should only be used for diagnostic purposes.
webex.Application.language : string
Kind: instance constant of
Read only: true
Since: 1.1.0
Properties
- language - Indicates the given language being used by the given meetings client. Example values: "en-US", "da-DK", etc.
webex.Application.setShareUrl(internalUrl, externalUrl, title, optionals) ⇒ Promise.<number>
Called by the initiator embedded app (the one specified by Start Page URL in the Developer Portal) to specify the URL of an app to share with meeting participants, or to add as a tab to a space.
- Calling
setShareUrl()
in a meeting causes the Open Together button to appear in the initiator app's window. Clicking this button opens the specified URL for all meeting participants. - Calling
setShareUrl()
in a space causes the Add to Tab button to appear in the initiator app's window. Clicking this button adds the specified URL to the space as a new tab.
Notes:
The first parameter to
setShareUrl()
(internalUrl
) is required and specifies the URL of an embedded app to open for meeting participants or add as a tab to a space. This app at this URL should integrate with the Embedded App Framework.The second parameter (
externalUrl
) is optional and specifies the URL of a version of your application that does not integrate with the Embedded App Framework. In a space this URL is used for the "Open in Browser" and "Copy URL" menu items in the tab added to the space.When invoked in a space context the initiator app must pass a value for the
title
parameter. If you don't want to provide an external URL for your application then pass an empty string for the second parameter, for example:app.setShareUrl("https://www.example.com/app/", "", "Tab name")
Kind: instance method of
Returns: Promise.<number>
- Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 2 = INVALID_ARGUMENT
Since: 1.1.0
Param | Type | Description |
---|---|---|
internalUrl | string | URL of an application that integrates with the Embedded App Framework to share with meeting participants, or add as a tab to a space. (Max length: 2083 characters) |
externalUrl | string | URL of a version of your application that does not require the Embedded App Framework. This URL is opened in Messaging spaces when a user selects the Open in Browser or Copy URL tab menu items. (Max length: 2083 characters). |
title | string | Title of the window or tab, depending on whether the app is running in a meeting or space. (Max length 256 characters.) |
optionals | object | Empty JSON object, not currently used. |
webex.Application.clearShareUrl()
Kind: instance method of
Summary: Clears the URL that was previously set using setShareUrl.
Since: 1.1.0
webex.Application.on(eventName, callback)
Kind: instance method of
Summary: Called when a given event is raised.
Since: 1.1.0
Param | Type | Description |
---|---|---|
eventName | string | one of the supported events |
callback | function | Function called when a given event is raised. Callback function will carry the event data. |
webex.Application.off(eventName)
Kind: instance method of
Summary: Stop listening to a given event.
Since: 1.1.0
Param | Type | Description |
---|---|---|
eventName | string | Name of the event to stop listening to. |
webex.Application.listen() ⇒ Promise.<void>
Kind: instance method of
Summary: Register to listen for incoming events.
Fulfill:
Since: 1.1.0
webex.Application.stopListening()
Kind: instance method of
Summary: Stop listening to all events.
Since: 1.1.0
webex.Application.onReady() ⇒ Promise.<void>
Kind: instance method of
Summary: Called when the Webex.Application object has been initialized and the SDK is ready for 3rd party consumption.
Fulfill:
Since: 1.1.0
Webex.Application.ErrorCodes
Enumeration of error codes returned by API methods.
Kind: static enum of
Read only: true
Since: 1.1.0
Properties
- 0 - Operation completed successfully.
- 1 - Call failed but arguments were incorrect.
- 2 - Call failed due to invalid arguments.
- 3 - Call to register an event failed because the event is already registered.
- 4 - Call to register an event failed because the event name is unknown to the framework.
- 5 - Call failed because it's not supported in the current context (Meeting or Space, for example).
- 6 - Call failed because the feature is not supported.
- 7 - Call failed because the framework has not initialized. Make sure your applications waits for the
onReady()
to resolve before making any method calls to the framework. - SUCCESS - Operation completed successfully.
- GENERIC_ERROR - Call failed but arguments were incorrect.
- INVALID_ARGUMENT - Call failed due to invalid arguments.
- EVENT_ALREADY_REGISTERED - Call to register an event failed because the event is already registered.
- EVENT_UNKNOWN - Call to register an event failed because the event name is unknown to the framework.
- BAD_CONTEXT - Call failed because it's not supported in the current context (Meeting or Space, for example).
- NOT_SUPPORTED - Call failed because the feature is not supported.
- NOT_INITIALIZED - Call failed because the framework has not initialized. Make sure your applications waits for the
onReady()
to resolve before making any method calls to the framework.
Webex.Application.Context
Application context object that exposes methods for getting information about users, meetings, and spaces. It is exposed as a context
property on the Webex Application instance.
Example usage
var app = new window.Webex.Application();
app.onReady().then(() => {
app.context.getUser().then((user) => {
console.log("getUser() promise resolved. User", user);
}
).catch((error) => {
console.log("getUser() promise failed " + error.message);
})
});
- Webex.Application.Context
- webex.Application.Context.getUser() ⇒ |
number
- webex.Application.Context.getMeeting() ⇒ |
number
- webex.Application.Context.getSpace() ⇒ |
number
webex.Application.Context.getUser() ⇒ | number
Returns a promise for a User object if successful, or a numeric error code if rejected. Example usage
var app = new window.Webex.Application();
app.onReady().then(() => {
app.context.getUser().then((m) => {
console.log('getUser()', m);
}).catch((error) => {
console.log('getUser() promise failed with error', Webex.Application.ErrorCodes[error]);
});
}
Kind: instance method of
Fulfill: - A User object
Reject: number
- Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR
Since: 1.1.0
webex.Application.Context.getMeeting() ⇒ | number
Returns a promise for a Meeting object if successful, or a numeric error code if rejected. A BAD_CONTEXT
error code (5) is returned if the method is called outside the context of a Meeting (in a Space, e.g.).
Example usage
var app = new window.Webex.Application();
app.onReady().then(() => {
app.context.getMeeting().then((m) => {
console.log('getMeeting()', m);
}).catch((error) => {
console.log('getMeeting() promise failed with error', Webex.Application.ErrorCodes[error]);
});
}
Kind: instance method of
Fulfill: - A Meeting object.
Reject: number
- Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 5 = BAD_CONTEXT
Since: 1.1.0
webex.Application.Context.getSpace() ⇒ | number
Returns a promise for a Space object if successful, or a numeric error code if rejected. A BAD_CONTEXT
error code (5) is returned if the method is called outside the context of a Space (in a Meeting, e.g.).
Example usage
var app = new window.Webex.Application();
app.onReady().then(() => {
app.context.getSpace().then((m) => {
console.log('getSpace()', m);
}).catch((error) => {
console.log('getSpace() promise failed with error', Webex.Application.ErrorCodes[error]);
});
}
Kind: instance method of
Fulfill: - A Space object
Reject: number
- Index to the static ErrorCodes array. 0 = SUCCESS, 1 = GENERIC_ERROR, 5 = BAD_CONTEXT
Since: 1.1.0
anchorType Definitions
anchorMeeting
Represents a Meeting object returned by a call to app.context.getMeeting().
Properties
- id
string
- Meeting ID. If app.isPrivateDataAvailable istrue
the value is a real meeting ID, otherwise it's a derived meeting ID. Derived IDs are guaranteed to be consistent for all users of the meeting. - title
string
- Title of the given meeting; blank if app.isPrivateDataAvailable is false. - startTime
string
- Start time of the given meeting, if available, for example, "2021-01-17T13:00:00.00Z". Blank if not available. - endTime
string
- End time of the given meeting if available, for example, "2021-01-17T13:00:10.00Z". Blank if not available. - conferenceId
string
- Conference ID. A unique ID that's created when then the first participant joins a meeting. If app.isPrivateDataAvailable istrue
then the value is a real conference ID, otherwise it's a derived conference ID. Derived IDs are guaranteed to be consistent for all users of the meeting. - userRoles
Array.<string>
- Represents the given users role(s). Can be 1 or more of these possible string values: "PARTICIPANT", "GUEST", "HOST", "COHOST", "PANELIST", and "PRESENTER". - meetingType
string
- Information about the meeting type. Can be one of: "MEETING", or "EVENT".
Space
Object that represents a Space object returned by a call to app.context.getSpace().
Properties
- id
string
- Space ID. Can be a real space ID or a derived space ID. If app.isPrivateDataAvailable is true then the real ID is used, otherwise the derived ID is used. - title
string
- Title of the given space; blank if app.isPrivateDataAvailable is false.
User
Object that represents a User object returned by a call to app.context.getUser().
Properties
- id
string
- Can be a real user ID or a derived user ID if app.isPrivateDataAvailable is false. - orgId
string
- Organization ID. Can be a real organization ID or a derived org ID if app.isPrivateDataAvailable if false. - email
string
- Email of the given user or blank if app.isPrivateDataAvailable is false. - displayName
string
- Display name of the given user or blank if app.isPrivateDataAvailable is false. - token
string
- JWT token for the given user.
anchorEvents
anchorThe following events are generated by the framework in response to modifications to application state, meeting or space details, or user roles.
application:shareStateChanged
Event fired when the sharing state of a shared URL changes. See Responding to Events for details on event handling.
Properties
- isShared
boolean
- Indicates if sharing is taking place.
application:displayContextChanged
Event fired when the rendering context of the application changes, for example, when a user pops out the app from the sidebar to a new window. See Responding to Events for details on event handling.
Properties
- displayContext
string
- Indicates the new display context.
application:themeChanged
Event fired when the user selects a new application theme. See Responding to Events for details on event handling.
Properties
- theme
string
- Indicates the current theme, LIGHT or DARK.
meeting:infoChanged
Fired when meeting information has changed for the given meeting.
Properties
meeting:roleChanged
Event fired when the role for the current participant changes.
Properties
- userRoles
string
- User role.
space:infoChanged
Event fired when space information changes, for instance the space title.
Properties