Class Application

Clears the URL previously set using setShareUrl() and removes the Open Together or Add to Tab button.

Remarks

Available since 1.1.0

Example

const app = new webex.Application();
await app.onReady();
app.clearShareUrl()

Initiates a single sign-on (SSO) authentication flow with a third-party identity provider in the system web browser at the specified URL. Returns a promise containing an OAuth authorization code from the ID provider, or a error code number.

WARNING initiateSystemBrowserOAuth is not supported in Webex for Government (FedRAMP).

In addition to any OAuth parameters required by the ID provider, the specified URL's redirect_uri query parameter must be set to https://oauth-helper-prod.wbx2.com/helperservice/v1/callback.

This callback correlates the authorization code returned by the identity provider with the embedded app that initiated the OAuth flow, and communicates that information back to your embedded app.

Notes:

The Valid domains configuration option for your embedded app must include the domain for the SSO page URL you pass to initiateSystemBrowserOAuth() (accounts.example.com, for example).

Returns

{Promise.<string | number>} - Authorization code that the embedded app can exchange for an ID or access token from the SSO provider.

Example

// Variable to save authorization code
let authCode;
// Initiate SSO flow
app.initiateSystemBrowserOAuth("https://accounts.example.com/auth?client_id=...&redirect_uri=https://oauth-helper-prod.wbx2.com/helperservice/v1/callback")
  .then(function (response) {
    // Get authorization code from JSON response
    console.log("initiateSystemBrowserOAuth() succeeded")
    authCode = response;
    // Exchange authorization code for a token with the SSO provider. This part of the OAuth flow
    // is the responsibility of the embedded app, e.g.
    exchangeCodeForToken(authCode);
  })
  .catch(function (reason) {
    console.error("initiateSystemBrowserOAuth() failed with reason=",
                   window.webex.Application.ErrorCodes[errorcode]
    );
  }

Remarks

Available since 1.5.0

Helper function that returns true if the client (Webex or Meeting Center app) supports a given version of the embedded apps SDK. The framework supports major.minor and major.minor.patch versioning. For example, "1.4" and "1.4.1" are valid version string formats, but "1" or "1.4.5.1" are not.

Also note that "1.4" is identical to "1.4.0".

Returns

{boolean}

Remarks

Available since 1.5.0

Example

The following checks if the Webex or Meeting Center app supports the "1.5.0" SDK version to determine if it can call the app.initiateSystemBrowserOAuth() method. ```javascript if(app.isSdkSupported("1.5.0")) { // Client supports initiateSystemBrowserOAuth() method, initiate SSO flow: app.initiateSystemBrowserOAuth("https://...") } ```

Used to register an event listener for a specified event. Either returns a successful Promise indicating that your app is ready to listen for events, or a failed promise indicating an error occurred. The listener must be registered after the app.onReady() promise has successfully completed.

Example

app.onReady().then(() => {
   log('onReady()', { message: 'host app is ready' })
   app.listen().then(() => {
      app.on('space:infoChanged', (payload) => log('space:infoChanged', payload));
   })
});

Returns

{Promise.<void>}

Remarks

Available since 1.1.0

Stops listening for the specified event.

Remarks

Available since 1.1.0

Registers a listener function to be called when the specified event is raised. Your app must first call app.listen() before registering listeners for specific events.

Remarks

Available since 1.1.0

Example

The following registers a listener for the `space:infoChanged` event that logs the Space object it receives as an event object to the console. ```javascript var app = new window.webex.Application(); app.onReady().then(() => { log('onReady()', { message: 'host app is ready' }) app.listen().then(() => { app.on('space:infoChanged', (payload) => log('Space info:', payload)); }) }); ```

Called when the webex.Application object has been initialized and the SDK is ready for use by your app.

Returns

{Promise.<void>}

Remarks

Available since 1.1.0

Example

The following example waits for `onReady()` before logging the main webex.Application object to the JavaScript console. ```javascript var app = new window.webex.Application();

app.onReady().then(function () { console.log('App is ready. App info:', app); }); ```

Opens an HTTPS or custom protocol URL in the default system browser. The specified URL must use https: or a custom protocol, such as webexteams: (to open the Webex app) or mailto: (to open the default mail app).

HTTPS URLs are validated against the list of allowed domains specified by the embedded app's configuration options. If a URL's domain doesn't match one of the app's allowed domains, or if it uses the http: protocol, then the call fails and an ACCESS_DENIED error is returned.

For URLs that specify custom protocols, the user is presented with a dialog asking them to allow or deny the request to open the app associated with the specified protocol. If the user clicks Open external link then Webex opens the associated app. Users can optionally save their preference to always open the associated app. User preferences are stored in local storage. If the user clicks Cancel then the call fails and an ACCESS_DENIED error is returned.

Returns

{Promise.<void>}

Remarks

Available since 1.4.0

Example

The following custom function passes a Webex teams space URL ("webexteams:") to `openUrlInSystemBrowser()`. If an error occurs the error message is displayed in the JavaScript console. ```javascript function openTeamSpace() { app.openUrlInSystemBrowser("webexteams://im?space=87a7b58d-bad1-4e2f-83c9-91aeb21c65f6").catch((errorcode) => { console.log("Error: ", window.webex.Application.ErrorCodes[errorcode]); }) } ```

Example

The following custom function opens an `https` URL. The URL's domain must match one of the embedded app's allowed domains. If an error occurs the error message is displayed in the JavaScript console. ```javascript function openSignInPage() { app.openUrlInSystemBrowser("https://www.example.com/signin").catch((errorcode) => { console.log("Error: ", window.webex.Application.ErrorCodes[errorcode]); }) } ```

Sets the URL to share in a meeting or space. Calling this method in a meeting causes the Open Together button to appear. In a space, calling this method causes the Add to Tab button to appear.

Returns

{Promise} One of the following static ErrorCodes.

0 = SUCCESS, 1 = GENERIC_ERROR, 2 = INVALID_ARGUMENT

Remarks

Available since 1.1.0

Example

The following provides values for all three parameters to `setShareUrl()`. ```javascript const app = new webex.Application(); await app.onReady(); app.setShareUrl( "https://www.example.com/app_internal/", "https://www.example.com/app_external/", "Application name" ) ```

Example

The following demonstrates how to call `setShareUrl()` for a messaging space when you don't want users to open your app outside of Webex or Meeting Center. ```javascript const app = new webex.Application(); await app.onReady(); app.setShareUrl( "https://www.example.com/app_internal/", "", "Application name" ) ```

Removes all event listeners registered by your application.

Remarks

Available since 1.1.0