Basic Setup
Here are the basic steps for getting an Oracle Web channel set up.
What Do You Need?
- An Oracle Web Channel. Creating the channel generates the Channel ID and the Secret Key that you need to initialize the chat app.
- The URL of the Oracle Chat Server.
- The Oracle Web SDK (located under Oracle Native Client SDKs for OCI Native Environments) from Oracle Technology Network’s ODA and OMC download page. Download this ZIP and extract it to your local system. This ZIP includes a user guide that describes the SDK's classes and a sample app that demonstrates many of its features.
Configure the Oracle Web Channel
-
Authentication is enforced using JSON Web Tokens (JWT). The customer's backend server generates the JWT token, which is then passed to the Oracle Web SDK. This token is used for each request to an ODA speech, text, or attachment server.NoteWhen the web app needs to connect to an ODA server, it first requests the token from the backend server and then adds it to the Authorization header. The ODA server validates the token, evaluates the claims, and then either opens the socket or rejects the connection.
To protect access to the channel, the token must always be generated by a remote server. It must never be generated within the client browser.Tip:
This article steps you through running the SDK with an authenticated channel. - Unauthenticated mode – Use the unauthenticated mode when the client can't generate signed JWT tokens, when no authentication mechanism is in place, or when the client widget is already secured and visible to authenticated users.
- Choose Development, then Channels from the menu.
- Choose Users.
- Click Add Channel and then Oracle Web as the channel type.
- Complete the dialog:
- Enter the channel name.
- For authenticated connections:
- Switch on the Client Authentication Enabled toggle to determine whether the SDK is connecting to a client authentication-enabled channel.
- The channel will only communicate with the sites
from the domains that you add as a comma-separated list. For
example,
*.corp.example.com
,*.hdr.example.com
. Entering a single asterisk (*) allows unrestricted access to the channel from any domain. Typically, you'd only enter a single asterisk during development. For production, you would add an allowlist of domains. - In the Max. Token Expiration (Minutes) field, set the maximum amount of time for the JWT token.
- For unauthenticated connections:
- Switch off Client Authentication Enable toggle.
- Enter a comma-separated list of domains that can
access the channel. If the domains in this allowlist includes
asterisks (
*.hdr.example.com
) or if the allowlist is not completely known, then you might consider an authenticated connection.
- Set the Session expiration time.
- Click Create. Oracle Digital Assistant will generate the Channel ID and the Secret Key that you need to initialize the SDK. Keep these close at hand because you'll need them when configuring the HTML page to host the chat widget.
- Route the channel to your skill or digital assistant.
- Switch Channel Enabled to On.
Tutorial: Secure Your Oracle Web SDK Chat
You can get a hands-on look at securing the Web chat widget through this tutorial: Secure Your Oracle Web SDK Chat.
Install the SDK
- In the extracted ZIP file of the downloaded Oracle Web SDK, locate
the
web-sdk.js
file (located in thenative-client-sdk-js
directory). - Save
web-sdk.js
(located in thenative-client-sdk-js
directory of the extracted ZIP) in your project directory. Note the file location, because you'll need it to define the<WebSDK URL>
property in the<script>
tag's code. - Create a JavaScript file with the following function that
initializes the SDK. We call this file
settings.js
in the sample that ships with the SDK.//settings.js var chatSettings = { URI: '<Server URI>', channelId: '<Channel ID>', userId: '<User ID>' }; function initSDK(name) { // If WebSDK is not available, reattempt later if (!document || !WebSDK) { setTimeout(function() { initSDK(name); }, 2000); return; } // Default name is Bots if (!name) { name = 'Bots'; } setTimeout(function() { var Bots = new WebSDK(chatSettings); // Initiate library with configuration var isFirstConnection = true; Bots.on(WebSDK.EVENT.WIDGET_OPENED, function() { if (isFirstConnection) { Bots.connect() // Connect to server .then(function() { console.log('Connection Successful'); }) .catch(function(reason) { console.log('Connection failed'); console.log(reason); }); isFirstConnection = false; } }); window[name] = Bots; }, 0); }
- Define the following properties:
URI
- The host name in Oracle Digital Assistant instance URL. Only the first path (/
) needs to be passed here. You can pass this URL either with, or without, the protocol (https://
).channelId
- The Channel ID that's generated when you create the Oracle Web channel. This property is required because connects the widget to the underlying skill.userId
- A user ID. When you provide this value, the user base for this skill can be tracked by the unique user metrics in Insights. When you don't provide a user ID, but the SDK will generate one with each new session. This property is optional for unauthenticated connections.
- In your HTML page, reference the locations of both the your JS file
(
setting.js
in the following example) theweb-sdk.js
library and the Web SDK namespace, which is typicallyBots
. Use this namespace to invoke the public APIs. For example, if you set the namespace toBots
, then you invoke the APIs asBots.<API>()
. To find out more about the various functions and events, refer to the user guide (available as both a readme and HTML doc) that's included in the Oracle Web SDK ZIP file.<script src="scripts/settings.js"></script> <script src="scripts/web-sdk.js" onload="initSdk('Bots')"></script>
Import the Library Using the Asynchronous Module Definition API
requirejs(['<path of the web-sdk>'], function(WebSDK) {
var settings = {
URI: '<Server URI>',
channelId: '<Channel ID>',
userId: '<User ID>'
};
Bots = new WebSDK(settings);
Bots.connect();
});
Import the Library Dynamically with JavaScript
function fetchSDK(src, onloadFunction, name) {
var script = document.createElement('script');
script.type = 'application/javascript';
script.async = true; // load the script asynchronously
script.defer = true; // fallback support for browsers that does not support async
script.onload = function() {
onloadFunction(name);
};
document.head.appendChild(script);
script.src = src;
}
fetchSDK('<path of the web-sdk>', initSDK, '<WebSDK namespace>');
Configure Client Authentication
In addition to using lists of allowed domains, client authentication is enforced by signed JWT tokens.
The token generation and signing must be done by the client in the backend server (
preferably after user/client authentication) which is capable of maintaining the
keyId
and keySecret
safe.
When the SDK needs to establish a connection with the ODA server, it first requests a JWT token from the client and then sends it along with the connection request. The ODA server validates the token signature and obtains the claim set from the JWT payload to verify the token to establish the connection.
clientAuthEnabled: true
must be passed in the SDK settings
parameter, and a token generator function must be passed as the second parameter. The
function must return a Promise, which is resolved to return a signed JWT token
string.//settings.js
var chatSettings = {
URI: '<Server URI>',
clientAuthEnabled: true
};
function generateToken() {
return new Promise(function(resolve) {
fetch('https://yourbackend.com/endpointToGenerateJWTToken')
.then(function(token) {
resolve(token);
})
.catch(function(error) {
console.log('Token generation error:', error);
});
});
}
function initSDK(name) {
// If WebSDK is not available, reattempt later
if (!document || !WebSDK) {
setTimeout(function() {
initSDK(name);
}, 2000);
return;
}
// Default name is Bots
if (!name) {
name = 'Bots';
}
setTimeout(function() {
var Bots = new WebSDK(chatSettings, generateToken); // Initiate library with configuration
var isFirstConnection = true;
Bots.on(WebSDK.EVENT.WIDGET_OPENED, function() {
if (isFirstConnection) {
Bots.connect() // Connect to server
.then(function() {
console.log('Connection Successful');
})
.catch(function(reason) {
console.log('Connection failed');
console.log(reason);
});
isFirstConnection = false;
}
});
window[name] = Bots;
}, 0);
}
The JWT Token
iat
- issued at timeexp
- expiry timechannelId
- channel IDuserId
- user ID
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzY3NDcyMDUsImV4cCI6MTU3Njc1MTExNywiY2hhbm5lbElkIjoiNDkyMDU5NWMtZWM3OS00NjE3LWFmOWYtNTk1MGQ2MDNmOGJiIiwidXNlcklkIjoiSm9obiIsImp0aSI6ImQzMjFjZDA2LTNhYTYtNGZlZS05NTBlLTYzZGNiNGVjODJhZCJ9.lwomlrI6XYR4nPQk0cIvyU_YMf4gYvfVpUiBjYihbUQ
- Header:
{ "typ": "JWT", "alg": "HS256" }
- Payload:
{ "iat": 1576747205, "exp": 1576748406, "channelId": "4920595c-ec79-4617-af9f-5950d603f8bb", "userId": "John" }