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

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:
  1. Choose Development, then Channels from the menu.
  2. Choose Users.
  3. Click Add Channel and then Oracle Web as the channel type.
  4. 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.
  5. Route the channel to your skill or digital assistant.
  6. 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

  1. 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).
  2. 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.
  3. 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
const 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()
 {
 		const Bots = new WebSDK(chatSettings);
 // Initiate library with configuration
 		let isFirstConnection = true;
 		Bots.on(WebSDK.EVENT.WIDGET_OPENED, async () => {
 			if (isFirstConnection) {
 				try {
 					await Bots.connect(); // Connect to server
 					console.log('Connection Successful');
 				} catch (error) {
 					console.log('Connection failed');
 					console.log(error);
 				}
 				isFirstConnection = false;
 			}
 		});

 		window[name] = Bots;
 	}, 0);
 }
  4. 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.
  5. 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.
       <script src="scripts/settings.js"></script>
   <script src="scripts/web-sdk.js" onload="initSdk('Bots')"></script>

Load the SDK from a CDN

You can also load the Web SDK from Oracle's Content Delivery Network (CDN). Using a CDN can offer such benefits as faster load times because of geographically distributed servers and a reduced hosting burden because you won't need to host the web-sdk.js file yourself.

Note:

This approach simplifies deployment by offloading the hosting of the Web SDK file to a CDN while you maintain control over your specific chat configurations via the settings.js file.
The setup is similar to the HTML Script Tag method, with the main difference being the source of the web-sdk.js file.
  1. Create your settings.js file: This file will contain your SDK configuration and the initSDK function. The purpose of this file and its contents are the same as those described in the HTML Script Tag section. You still host this settings.js file yourself.
  2. Link settings.js and the CDN-hosted web-sdk.js in your HTML file: In your HTML page's <head> section, include one script tag for your locally hosted settings.js file and another for the Web SDK, pointing the src attribute to the CDN URL.
    <head>
   <!-- 1. Your custom settings -->
    <script src="settings.js" defer></script>
   <!-- 2. Web SDK from CDN -->
   <script src="https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js" onload="initSDK('<WebSDK namespace>')" defer></script>
   <!--
      Option A: Example with a specific version
      <script src="https://static.oracle.com/cdn/oda/25.4.0/web-sdk.js" onload="initSDK('Bots')" defer></script>
             Option B: Latest Stable Version (Convenient for always getting updates)
      <script src="https://static.oracle.com/cdn/oda/latest/web-sdk.js" onload="initSDK('Bots')" defer></script>
      -->
   <!--
      Important Notes for the CDN script tag (choose one option from above):
      - Replace 'https://static.oracle.com/cdn/oda/<VERSION>/web-sdk.js' with the actual CDN URL provided for the Oracle Web SDK.
      - For Option A: Replace '<VERSION>' in the URL with the specific SDK version number you need (e.g., '25.4.0').
      - For Option B: Using 'latest' instead of a specific version number will always load the most recent stable release.
      - See the 'Oracle CDN URLs' section below for a list of available versions and more details.
      - Replace '<WebSDK namespace>' (e.g., 'Bots' in the examples) with your chosen name for the SDK instance.
      -->
</head>
CDN URLs
The Oracle Web SDK can be loaded from the following official CDN URLs.

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.config({
     paths: {
         WebSDK: '<path of the web-sdk>' // replace this with actual library path
     } });

 define(['WebSDK'], function(WebSDK)
 {     const 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) {
    const 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('', initSDK, '');

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.
async function generateToken() {
    const token = await fetch('https://yourbackend.com/endpointToGenerateJWTToken');
    return token;

}

Bots.init({
    URI: 'oda-instance.com',
    clientAuthEnabled: true
}, generateToken);

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:
Encoded:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpYXQiOjE1NzY3NDcyMDUsImV4cCI6MTU3Njc1MTExNywiY2hhbm5lbElkIjoiNDkyMDU5NWMtZWM3OS00NjE3LWFmOWYtNTk1MGQ2MDNmOGJiIiwidXNlcklkIjoiSm9obiIsImp0aSI6ImQzMjFjZDA2LTNhYTYtNGZlZS05NTBlLTYzZGNiNGVjODJhZCJ9.lwomlrI6XYR4nPQk0cIvyU_YMf4gYvfVpUiBjYihbUQ
Decoded:
  • Header:
    {
    "typ": "JWT",
    "alg": "HS256"
}
  • Payload:
    {
    "iat": 1576747205,
    "exp": 1576748406,
    "channelId": "4920595c-ec79-4617-af9f-5950d603f8bb",
    "userId": "John"
}
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.