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
    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);
    }
  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>    

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:
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.