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 π
You can configure the channel to connect to the ODA speech, text, or attachment
server in two modes: authenticated (to protect access to the channel) or
unauthenticated.
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.
Note
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.
When 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.
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.
To configure the Oracle Web channel:
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.
In the extracted ZIP file of the downloaded Oracle Web SDK, locate
the web-sdk.js file (located in the
native-client-sdk-js directory).
Save web-sdk.js (located in the
native-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) the
web-sdk.js library and the Web SDK namespace, which is
typically Bots. Use this namespace to invoke the public APIs.
For example, if you set the namespace to Bots, then you invoke
the APIs as Bots.<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.
Import the Library Using the
Asynchronous Module Definition API π
You can import the library using implementations of the Asychronous Module
Definition (AMD) API such as RequireJS with Oracle JET, and SystemJS.
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 π
Use the following Mozilla Development Network
(MDN)-based utility function to 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.
To enable this mode, these two fields are required during SDK initialization:
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 π
The client app is responsible for the JWT token generation. Some of the token
payload fields are mandatory and are validated by the ODA server. Clients must use the
HS256 signing algorithm to sign the tokens. The body of the token must have the
following claims:
iat - issued at time
exp - expiry time
channelId - channel ID
userId - user ID
The tokens themselves must be signed by the secret key of the client auth-enabled
channel to which the connection is made. Hereβs a sample signed JWT token:
If any claim in the token is missing or has incorrect format for its value, then an
error message is thrown by the SDK describing the cause. The connection is not
attempted. The error message can be used to fix the issue with the JWT token. Any
additional claims passed in the payload do not affect the client authentication
mechanism.