Overview

The Client Apps framework lets you embed custom web-based applications in the Genesys Cloud web or desktop client. Apps can be displayed in the sidebar, main stage, or in interaction widget panels.

<div class='container-flex'> <div class='row'> <div class='col-md-4'> <h3>Widget (Sidebar)</h3> <p> Widget apps are available in tabs for quick switching between apps. </p> <img src='./images/widget.png' width='100%'> </div> <div class='col-md-8'> <h3>Standalone</h3> <p> Standalone apps are deep linkable (e.g. https://apps.mypurecloud.com/directory/#/apps/c3bd49e1-8ce3-4580-8743-174012722316) within your org. </p> <img src='./images/standalone.png' width='100%'> </div> </div> <div class='row'> <div class='col-md-8'> <h3>Interaction Widget</h3> <p> Interaction Widget applications are contextually sensitive to an individual interaction. Each interaction gets a custom instance of the application (when access controls and filters dictate display of the app). Switching between Genesys Cloud interactions switches/loads a seperate instance of an interaction widget application. Up to 10 instances of Interaction Widget apps can run concurrently. <p> <img src='./images/interactionWidget.gif' width='100%'> </div> </div> </div> <br/>

Genesys Cloud is hosted in a HTTPS location so browser security requires that Client Apps are also hosted on an HTTPS URL. For development purposes, using a self-signed localhost certificate is fine, but the certificate will either need to be installed for your browser, or accepted by navigating to the URL directly and accepting the untrusted certificate.

There is a specific Client App Javascript SDK to expose client side functionality. If you wish to deal with server side resources, the Platform API is available as well as the Platform Javascript SDK. To get an authorization token, your app will need to go through the Implicit Grant or Authorization Code OAuth flow.

Data can be seeded into an app (Standalone, Widget, or Interaction Widget) via URL string replacement. When specifying the url to your app, you can include specific tokens which will be replaced when your app is loaded. The URL

https://myapp.example.com?langTag={{gcLangTag}}&gcTargetEnv={{gcTargetEnv}}&gcHostOrigin={{gcHostOrigin}}&conversationId={{gcConversationId}}&usePopupAuth={{gcUsePopupAuth}}

would contain information on the user's preferred language, which environment they are running in, the applicable conversation context, and the organization's popup auth setting. With the tokens replaced, it might look like:

https://myapp.example.com?langTag=en-us&gcTargetEnv=prod&gcHostOrigin=https%3A%2F%2Fapps.mypurecloud.com&conversationId=85ff71c0-f96d-45f6-9d98-fa5e01b22af8&usePopupAuth=true

Interpolation does not need to happen in just the query string, it can happen anywhere in the URL

https://myapp.example.com/{{gcLangTag}}/index.html

Application icons can be specified in the advanced section of your application configuration. Icons are used as the tab icon for Widget and Interaction Widget Apps and as a splash icon in the center of the app viewport while the app is loading.

"icon": {
"vector": "",
"24x24": "",
"36x36": "",
"48x48": "",
"72x72": ""
},
"monochromicIcon": {
"vector": "",
"24x24": "",
"36x36": "",
"48x48": "",
"72x72": ""
}

A vector icon will always be preferred over the raster versions. If no vector is specified, a raster icon will be selected based on the screen resolution and context in which the icon is being rendered.

When specified, a monochromic icon will be used within Genesys Cloud controls. They should contain only a single color (for stroke and fill) but can contain transparencies. Monochromic icons are preferred as the Genesys Cloud UI can manipulate the foreground and background colors to make the app feel more native. You should only specify a monochromic icon if the icon is allowed to be manipulated dynamically.

If an icon is specified, it will always be used in the splash page icon presented as your app loads. This allows your branding to be shown while the app loads but creates a more integrated feel with the Genesys Cloud UI during the rest of the user experience.

Several Example/Demo apps are available on GitHub to illustrate how to build a Client App and how to use the Client Apps SDK. Some of these examples can be embedded directly via the github.io URL. Others will require you to create an OAuth client in your org and host the example yourself. All the examples can be run and hosted locally by pulling the repo and running the command npm start or yarn start.