Using Client App SDK with Platform SDK
Introduction
This tutorial walks through the steps of integrating a web app with the Genesys Cloud Client App SDK and the Genesys Cloud Platform SDK.
The Client App SDK grants web applications access to unique functionalities when they're embedded as a Client App Integration or Interaction Widget.
The Javascript Platform SDK provides a way to consume the Genesys Cloud Platform API which is used in general purpose integrations with Genesys Cloud.
This tutorial shows how to set-up a simple integration using the two SDKs.
const clientId = '--- CLIENT ID HERE ---';
const redirectUri = 'http://localhost:8080/index.html';
const appName = 'sample_app';
const qParamLanguage = 'language';
const qParamEnvironment = 'environment';
// Default values are assigned but values should
// be set on the function 'assignConfiguration'
let language = 'en-us';
let environment = 'mypurecloud.com';
let userDetails = null;
/**
* Configure both the Platform SDK and the Client App SDK
*/
function setupGenesysClients(){
const platformClient = require('platformClient');
const client = platformClient.ApiClient.instance;
const usersApi = new platformClient.UsersApi();
// Configure Client App
let ClientApp = window.purecloud.apps.ClientApp;
let myClientApp = new ClientApp({
pcEnvironment: environment
});
// Configure and Authenticate Platform Client
client.setPersistSettings(true, appName);
client.setEnvironment(environment);
return client.loginImplicitGrant(clientId, redirectUri)
.then(data => usersApi.getUsersMe())
.then(data => {
userDetails = data;
myClientApp.alerting.showToastPopup(
`Hi ${userDetails.name}`,
'Never gonna give you up, never gonna let you down 😊');
})
.catch(err => console.log(err));
}
/**
* Assign the language and environment for the app first through
* the query parameters. But if non-existent, attempt to get
* it from localStorage. If none, use default values.
*/
function assignConfiguration(){
let url = new URL(window.location);
let searchParams = new URLSearchParams(url.search);
if(searchParams.has(qParamLanguage)){
language = searchParams.get(qParamLanguage);
localStorage.setItem(`${appName}_language`, language);
} else {
let local_lang = localStorage.getItem(`${appName}_language`);
if(local_lang) language = local_lang;
}
if(searchParams.has(qParamEnvironment)){
environment = searchParams.get(qParamEnvironment);
localStorage.setItem(`${appName}_environment`, environment);
} else {
let local_env = localStorage.getItem(`${appName}_environment`);
if(local_env) environment = local_env;
}
}
// After page loads...
window.addEventListener('load', (event) => {
assignConfiguration();
console.log(`environment: ${environment}`);
console.log(`language: ${language}`);
setupGenesysClients()
.then(() => {
// Display values to the page
document.getElementById('span_environment').innerText = environment;
document.getElementById('span_language').innerText = language;
document.getElementById('span_name').innerText = userDetails.name;
console.log('Finished setup.');
})
});
URL Interpolation to determine gcLangTag, gcHostOrigin and gcTargetEnv
Pre-Requisites:
- The configured app should have a URL defining the gcLangTag, gcHostOrigin and gcTargetEnv tags
ex. https://myapp.com?language={{gcLangTag}}&gcHostOrigin={{gcHostOrigin}}&gcTargetEnv={{gcTargetEnv}}This will contain information on the user's locale and which environment they are running and will look similarly to:
https://myapp.com?language=en-us&gcHostOrigin=https%3A%2F%2Fapps.mypurecloud.com&gcTargetEnv=prodAfter acquiring both the environment and language values from the query parameters, they will be persisted using the localStorage. This is important because in the Implicit Grant Authentication step, the page will be redirected without the query parameters values.
Once the page reloads and there are no query parameters, then it will attempt to reassign both the environment and language variables with the values that are stored in the localStorage.
/**
* Assign the language and environment for the app first through
* the query parameters. But if non-existent, attempt to get
* it from localStorage. If none, use default values.
*/
function assignConfiguration(){
let url = new URL(window.location);
let searchParams = new URLSearchParams(url.search);
if(searchParams.has(qParamLanguage)){
language = searchParams.get(qParamLanguage);
localStorage.setItem(`${appName}_language`, language);
} else {
let local_lang = localStorage.getItem(`${appName}_language`);
if(local_lang) language = local_lang;
}
if(searchParams.has(qParamEnvironment)){
environment = searchParams.get(qParamEnvironment);
localStorage.setItem(`${appName}_environment`, environment);
} else {
let local_env = localStorage.getItem(`${appName}_environment`);
if(local_env) environment = local_env;
}
}
Setting up the Client SDK
A ClientApp instance needs to be created with the correct environment for its configuration.
For more information on the Client App SDK, go to this page.
Implicit Grant Authentication
In order to use the Genesys Cloud API, an implicit grant authentication needs to be accomplished. After authentication it should redirect to the URL in the redirectUri variable.
For more information on authorization see this page.
Toast Popup
After setting up both the Client App SDK and the Platform SDK, they can now be used to their full advantages.
In this example, we use the Platform SDK to query the user details and then, using the Client App SDK, show a Toast up in order to greet them.
