Client App SDK
A JavaScript library to deeply integrate a 3rd-party applications within Genesys Cloud. This library handles App and UI-level integration concerns such as navigation, alerting, attention, and lifecycle management. For data access, plese use the Genesys Cloud Platform API Javascript Client.
Obtaining the library
NPM/Yarn
$ npm install purecloud-client-app-sdk
# -or-
$ yarn add purecloud-client-app-sdkGenesys Cloud CDN
https://sdk-cdn.mypurecloud.com/client-apps/2.6.7/purecloud-client-app-sdk.js
https://sdk-cdn.mypurecloud.com/client-apps/2.6.7/purecloud-client-app-sdk-<hash>.min.jsAccessing the Library
The Client Apps SDK is bundled in several formats to support your build ecosystem and deployment model.
Note: Although a CJS format is provided, it is to be consumed by tooling. This library is client-side and will not run in a node environment.
Best Practice
We recommend importing and using the library via a build tool such as webpack, rollup, broccoli, browserify, etc. This provides optimal control with respect to resource loading and bootstrapping. A UMD browser bundle is available for prototyping, quick demos, and build-less environments.
The Formats
- JavaScript/EcmaScript Modules (dist/main.mjs)
- CommonJS Module (dist/main.js)
- Browser UMD Module (dist/purecloud-client-app-sdk.js)
- Global:
purecloud.apps.ClientApp
<a name="formats-es"></a>
JavaScript/EcmaScript Modules (dist/main.mjs)
// JS/ES Modules
// Note: import syntax varies by tool
import ClientApp from 'purecloud-client-app-sdk';
let myClientApp = new ClientApp({
gcHostOriginQueryParam: 'gcHostOrigin',
gcTargetEnvQueryParam: 'gcTargetEnv'
});
myClientApp.alerting.showToastPopup('Hello', 'Genesys Cloud');<a name="formats-cjs"></a>
CommonJS Module (dist/main.js)
// CommonJS
let ClientApp = require('purecloud-client-app-sdk');
let myClientApp = new ClientApp({
gcHostOriginQueryParam: 'gcHostOrigin',
gcTargetEnvQueryParam: 'gcTargetEnv'
});
myClientApp.alerting.showToastPopup('Hello', 'Genesys Cloud');<a name="formats-umd"></a>
Browser UMD Module (dist/purecloud-client-app-sdk.js)
<!-- Script Tag -->
<!-- Note: You can use the script from our CDN or host it locally -->
<head>
<script src="https://sdk-cdn.mypurecloud.com/client-apps/2.6.7/purecloud-client-app-sdk-<hash>.min.js"></script>
</head>
<!--...-->
<script>
// Note: You may need to use another event (e.g. load ) depending on how you load the script.
document.addEventListener('DOMContentLoaded', function () {
var ClientApp = window.purecloud.apps.ClientApp;
var myClientApp = new ClientApp({
gcHostOriginQueryParam: 'gcHostOrigin',
gcTargetEnvQueryParam: 'gcTargetEnv'
});
myClientApp.alerting.showToastPopup('Hello', 'Genesys Cloud');
});
</script>Environments
The ClientApp instance must be configured to match the Genesys Cloud environment in which it is being run. The environment defaults to mypurecloud.com; however, you will likely need to support other environments.
Best Practice
We recommend configuring your app so the PC environment can be seeded into the url. This allows the SDK to dynamically determine the environment at runtime and simplifies your code.
- When registering your app, configure the URL in the format: https://myapp.mydomain.com?gcHostOrigin=\{\{gcHostOrigin\}\}&gcTargetEnv=\{\{gcTargetEnv\}\}
- Include
gcHostOriginQueryParam: 'gcHostOrigin'andgcTargetEnvQueryParam: 'gcTargetEnv'in your ClientApp config to dynamically determine the environment - Use
myClientApp.gcEnvironmentto access the environment later when needed (e.g. to pass to the Genesys Cloud Platform API Javascript Client.
Manual Configuration
You can also manually specify the Genesys Cloud environment or origin. For details on supported options, see ClientApp
Modules
Features of the SDK are bundled into modules and can be accessed from the root ClientApp instance.
Versioning
The Client Apps SDK uses SemVer to manage releases. SemVer enables you to safely upgrade in most cases without concern for breaking existing code. Note that this library's version does not relate to the version of the Genesys Cloud hosting app or the js platform SDK.
