Programming Pearls: Feature customizations and implementations using Oracle Web SDK Abhay Bhavsar and Rohit Dhamija, July 2020
Summary The purpose of this article is to provide a guidance to customer deploying digital assistant using the new Oracle Web SDK. It also explains the benefits of migrating from the deprecated 19.4.1 SDK to the new Oracle Web SDK 20.6.1 currently available on Generation 2 Oracle Cloud Infrastructure (OCI).
The Oracle Web SDK provides an extensive set of configurations and customizations using properties, event handlers and delegates. The article not only introduces the developers to various built-in capabilities but also provides some customizations that shows the extensibility of the SDK that are not available out of the box. It is assumed that you are familiar with client programming in JavaScript and understand basics of HTML/CSS. At the time of writing this article the latest version of Oracle Web SDK was 20.6.1.
Disclaimer Please be aware that while this document demonstrates possible feature implementation using the JavaScript Web SDK, you have to decide the cost of those features. For example, not all channels that your bot is used on would support the features described in this article. The code supplied with this article comes with no support, so use at your own risk.
TABLE OF CONTENTS
TABLE OF CONTENTS 2
Before You Begin 3
Running The Sample 3
SECTION – I – BASIC SETUP 5
BAS.Q.1 : Set up ODA Web Channel using Oracle Web SDK 6 BAS.Q.2 : Implement Bot Initiated Conversation 10 BAS.Q.3 : Change bot and person icons on the chat header and in the message window 11
SECTION – II – ENHANCING THE CHAT WIDGET 12
INT.Q.1 : Implement banners & quick service buttons 12 INT.Q.2 : Implement Close Button with Confirmation dialog box 13 INT.Q.3 : Adding a Menu to the header of the chat widget 14 INT.Q.4 : Send HTML formatted content as part of the message 17 INT.Q.5 : Embedding YouTube video inside ODA chat web-widget 18 INT.Q.6 : Upload files/attachments to ODA through Web Channel 19 INT.Q.7 : Perform clean-up after a user logged out or loses session 21 INT.Q.8 : Optimize longer bot messages displayed in the Oracle Web Messenger 22 INT.Q.9 : Extending Oracle Digital Assistant built-in Styles 24
SECTION – III – ADVANCED FEATURES 26
ADV.Q.1 : Using Inline forms to capture use information for simple use cases 26 ADV.Q.2 : Configure Voice Channel and support various skill voices depending on region 28 ADV.Q.3 : Test Oracle Digital Assistant Web Channels with Client Authentication Enabled 29
Before You Begin
• Ensure that you have access to the instance of Oracle Digital Assistant version 20.06 or later. • A few features may require access to Object Storage service on Oracle Cloud Infrastructure aka OCI. • Download the latest Oracle Digital Assistant Oracle Web SDK. https://www.oracle.com/downloads/cloud/amce-downloads.html • Download and extract the resources.zip file provided with this article to your local machine, it has the DA export and the Oracle Web SDK customized sample. - ITMgmtDA(1.1).zip - Web-SDK-Sample.zip
Running The Sample
• Import the Digital Assistant (DA). Train it. You may have the DA in Draft status.
Figure 1: Import Digital Assistant
• Extract the Web-SDK-Sample.zip file provided, the folder structure should look something like shown below:
Figure 2: Locate the sample and index.html • Double click on index.html, so that it opens this page on your browser. You will observe a chat widget icon on the bottom right of the browser page. Click on the chat widget, you will observe the screen something like below:
Figure 3: Launch chat widget Your chat-widget is ready, but wait, you cannot communicate with this digital assistant because you still need to set up the Oracle Web Channel and route your Digital assistant through it. So, let’s get started.
SECTION – I – BASIC SETUP
This section answers basic questions on how to set up an Oracle Web Channel and use basic features of the Oracle Web SDK. Here are some of the questions this section answers:
Q.1 How do I migrate from old 19.4.1 Web SDK to Oracle Web SDK 20.6.1 available on ODA 20.0x on OCI GEN2? Ans: Refer to BAS.Q.1 of this section.
Q.2 How to set up a new Oracle Web channel on Oracle Digital Assistant user interface? Ans: Refer to BAS.Q.1 of this section.
Q.3 I am new to Oracle Digital Assistant, help me expose my skill or digital assistant on my website. Ans: You can deploy the sample provided with this article on your web site. You may also choose to store all the SDK files on Oracle Cloud e.g. Object Storage and only make a small change on your web site to run the bot. The HTML code snippet in the index.html page shows a sample of what script you need to embed inside the HTML page of your web site. You can run the bot over a simple HTML page, an Oracle Visual Builder application or deployed on Oracle Content and Experience cloud.
Q.4 I need to make basic changes to the out of the box web interface to the sample provided with Oracle Web SDK. Ans: Refer to BAS.Q.3. This topic explains how to change the various icons and make basic UI changes to the chat widget. It also refers you to another article that provides a step-by-step guide on how to do this.
Q.5 May I continue using the existing 19.4.1 web channel and SDK on the migrated ODA 20.0x version on OCI GEN 2? Ans: Oracle strongly suggests moving to the Oracle Web channel using the latest Oracle Web SDK 20.6.1 or above. The Oracle Web SDK is very easy to configure, has built-in properties to perform some advanced features and is voice enabled. The old 19.4.1 web channel forces end user messages to be routed through a third party cloud while the Oracle Web SDK is a completely Oracle only solution. The old 19.4.1 channel will be discontinued in near future.
Q.6 My migrated instance works fine and my existing web channel continues to function, so why should I change? Ans: The existing channel is only provided so that the migration activity does not disrupt currently deployed bots. It is recommended to create a new Oracle Web Channel and use some techniques provided in this article to improve the overall user experience. You can approach the PM team who would be glad to assist in this migration.
Q.7 Can I edit the old web channel so that it can point to a newer version of my skill or DA? Ans: The old 19.4.1 web channel is deprecated and is only provided for a limited time. The channel is read only so that customers are encouraged to move to Oracle Web SDK.
YOUR EXISTING WEB CHANNEL (MIGRATED FROM 19.X TO 20.X) WILL BE READ ONLY AND YOU WILL NOT BE ABLE TO MAKE THE CHANGES TO THE CHANNEL, BUT THE CHANNEL RUNTIME WOULD WORK WITHOUT ANY ISSUE.
BAS.Q.1 : Set up ODA Web Channel using Oracle Web SDK You will learn to host and run Oracle Digital Assistant chat widget. The following screen shot shows a 19.4.1 web channel which is no longer supported. So we create a new Oracle Web channel.
Figure 4: Deprecated 19.4.1 Web Channel You have already imported the digital assistant and trained it. This topic discussed how to create the new Oracle Web channel and configure it to point to your DA. 1. Open Oracle Digital Assistant click on the top left hamburger menu and navigate to Channels menu 2. Under Users tab, click on + Channel button, as shown below:
Figure 5: Create new channel
3. Click the + Create Channel button and set the following options: a) Provide a name to the channel, e.g. ITMgmtBotWebChannel. b) Select Channel Type as Oracle Web. c) Under Allowed domains enter * d) Disable the client authentication enabled option. e) Click on the Create button.
Figure 6: Creating a new channel.
The Allowed Domains restricts this channel from being communicated by specific domains to ensure anonymous web sites or test pages do not send messages to this channel. Note: For this section, please set the Allowed Domains to *. You will run the sample web page locally on your computer (so no domain involved). The client authentication mechanism is explained in the advanced section of this article.
4. Now set Route to ITMgmtDA digital assistant and toggle the Channel Enabled switch to show enabled.
Figure 7: Configure oracle web channel
5. Next, please take a note of the Channel Id, as well as the Oracle Digital Assistant instance URI as shown in the image below. You need the ODA URI & Channel ID for configuring the chat widget.
Figure 8: Copy URI from address bar
6. Configure the downloaded sample to point to your Oracle Web channel you just created. a) Locate the web folder extracted from the Web-SDK-Sample.zip file. b) Open settings.js (web/script/settings) and update values for URI and channel ID
Note: The URI does not contain the protocol i.e. https://
f) Save settings.js file and close it g) Run the index.html in your browser.
Figure 9: Test your Oracle Web channel
BAS.Q.2 : Implement Bot Initiated Conversation Often it is considered a good user interface when the chat greets the end user as soon as they click on the chat widget. This can be used to display a list of services or simply provide a greeting message or even at times start a conversation. A) Objective As soon as the user opens the chat-widget, the user should be greeted with appropriate message(s). This is what we want to achieve in this topic.
B) View
Figure 10: Test your Oracle Web channel
C) Code Snippet You can use initUserHiddenMessage property to send once the chat widget is ready without displaying the message in the chat widget. This will be used to initiate the conversation automatically. Alternatively, the following code can be used to initiate the chat conversation:
Note that to keep the message from being displayed in the widget, you pass the hidden flag as true. D) Reference Material – Oracle Web SDK Documentation https://docs.oracle.com/en/cloud/paas/digital-assistant/sdk-js/index.html
BAS.Q.3 : Change bot and person icons on the chat header and in the message window
A) Objective Oracle Web SDK provides lots of UI customization options for layout, icons, colors, text and many more. This section describes how to easily you can change the icons used in the widge.
B) Code Snippet All you need to do is to add the icons property in chatWidgetSettings variable. Note that you can also store the images in Oracle Object Storage, ensure that the URLs point to the absolute URL of the image deployed to the storage.
// BAS.Q.2 Implement Bot Initiated Conversation
// initUserHiddenMessage : 'Hello', // BAS.Q.3 Change the chat icons and the icons displayed on the chat header window. botIcon: './images/botIcon.jpg', personIcon: './images/personIcon.jpg',
Figure 11: Some layout properties to assist branding
C) Reference Material
Overview of the new Oracle Web SDK and its customization features in Oracle Digital Assistant 19.10 and later: https://blogs.oracle.com/mobile/overview-of-the-new-oracle-web-sdk-and-its-customization-features-in-oracle- digital-assistant-1910-and-later
SECTION – II – ENHANCING THE CHAT WIDGET
This section will cover areas which are topics like customizing the chat widget, message delegates, including those not provided out of the box in the Oracle Web SDK. Customers would be able to compare the UI customizations they have done for the Smooch based UI and implement them in Oracle Web SDK.
INT.Q.1 : Implement banners & quick service buttons
A) Objective How do I create a chat how with banners and action buttons for better user experience? You can use various built-in properties to build the branding. This includes the bot icons as well as customization of the header, providing banners, etc. The following screenshot shows how the chatbot home screen is designed with a banner and a friendly message with buttons to report issues or request access.
B) View
Figure 12: Banners & Action Buttons
C) Code Snippet
The index.html page references a custom.js file. This JavaScript file has code to initialize the banner as well as a friendly message “How can I help you today?” as well as the buttons e.g. Setup Printer.
INT.Q.2 : Implement Close Button with Confirmation dialog box
A) Objective The Web SDK sample provides a minimize button that simply minimizes the chat window and shows the bot icon. But in order to end your conversation and clear the chat window you need to implement the close button For the close button there is a small customization to be added to the web-sdk-20-06-02.js file.
B) View
Figure 13: Close Button
C) Code Snippet
In the web-sdk-20-06-02.js file, the following code is added to add the close button besides the existing minimize icon. This is the only customization to the Oracle Web SDK. Note we are using 20.06.2 version of the SDK that has a patch to fix an issue with Bots.destroy() that this feature uses. if (typeof closeButton != 'undefined') r.appendChild(closeButton);
Disclaimer: You may wish to use the out of the box 20.6.1 or higher version of the web-sdk.js file and rest of the topics in this article would work fine. The Close button needs the above change. You may have to maintain this change in your SDK during future upgrades. So use this file only if you intend to maintain this change.
INT.Q.3 : Adding a Menu to the header of the chat widget
A) Objective Few customers have a requirement to have a drop-down menu within the chat header section. This menu would allow users to select an option, which would then explicitly navigate to a particular Skill’s Intent within the Digital Assistant.
B) View Here is what the final UI should look like:
Figure 14: Menu
C) Code Snippet
In the Functionality Configuration section in the Oracle Web SDK documentation, there is a property called customHeaderElementId. The purpose of this property is to define a HTML element ID of the particular
The following is the HTML snippet in index.html that created a header element DIV tag.
The initialize() function in the custom.js file implements this header. function initialize() { var el = document.getElementById("top-text"); el.innerHTML = el.innerHTML + "………
// CODE REMOVED FOR BREVITY – Check custom.js file for full code.
var el = document.getElementById("header-custom-element");
// CODE REMOVED FOR BREVITY – Check custom.js file for full code. }
The menu items thus added calls a JavaScript function to send a message using Bot.sendMessage(); function setupPrinter() { console.log("I need to set up a printer"); SendMsg('I need to set up a printer'); } function SendMsg(msg) { Bots.sendMessage(msg, { hidden: false }); }
D) Reference Material Tech Exchange Article: How To Create A Custom Drop-Down Menu In The Oracle Web SDK https://blogs.oracle.com/mobile/techexchange%3a-how-to-create-a-custom-drop-down-menu-in-the-oracle- web-sdk
INT.Q.4 : Send HTML formatted content as part of the message
A) Objective Oracle Web SDK supports HTML content to be delivered from the skill on the Web Channel. FAQ implemented using Answer intents is one simple use case. You can embed the HTML content right in the Answer or as part of the content in a resource bundle key. Oracle Web SDK supports rendering HTML content.
B) View
Figure 15: HTML rendering Look at the ITMgmtSkill and you will find a few Answer Intents e.g. Install VPN, you can find the corresponding HTML content for the above content. You can also embed links e.g. Download Here in this following example:
Sample Content You can install the Cisco AnyConnect Secure Mobility Client on your machine using Windows 10, Mac OSX 10.8 and above or Linux. To download and install the Cisco AnyConnect Secure Mobility Client: Inside your Network:
Launch MyDesktop.
Click Software.
Select All Software/Search.
Enter AnyConnect in the Search field.
Select the Cisco AnyConnect Client to install.
Follow online prompts.
You can also download by clicking on the link below
Download Here
INT.Q.5 : Embedding YouTube video inside ODA chat web-widget
A) Objective In this topic, you will learn how to embed YouTube videos in your chatbot conversations. B) View In the sample provided with this article enter message “My internet is down” in the message window.
Figure 16: YouTube Video You can specify a link to a YouTube video inside your content directly in Answer intents. You can also provide this in the resource bundle. You can also choose to use HTML tags and embed it in your content. C) Sample Content Here is a quick video: https://youtu.be/ZPW8UAaQR6w Here are a few steps to take when your Internet is down.
D) Reference Material Please refer the complete article and source code here: https://blogs.oracle.com/mobile/techexchange-quick-tip%3a-how-to-embed-youtube-videos-in-oracle-digital- assistant-web-sdk-web-messenger
INT.Q.6 : Upload files/attachments to ODA through Web Channel
A. Objective The Digital Assistant Client SDK for Oracle Web provides you with a widget that enables you to run a skill in a web page.
B) View
Figure 17: File Attachments
C) Code Snippet The Oracle Web SDK has an integrated document and image upload functionality that saves content in Oracle Cloud Infrastructure (OCI) storage service. Once the content is uploaded, the server returns a JSON payload similar to the payload shown below:
{ "messagePayload": { "attachment": { "type": "image", "URL": "http://your-oda-instance.com/attachment/v1/attachments/d43fd051-02cf-4c62-a422-313979eb9d55" }, "type": "attachment" }, "userId": "guest" }
You can access the attachment of the content of JSON payload my using custom component using the code snippet given below:
D) Reference Material Please refer this article for complete details: https://blogs.oracle.com/mobile/techexchange-quick-tip%3a-how-to-upload-documents-in-an-oracle-digital- assistant-web-conversation-using-the-oracle-web-sdk
INT.Q.7 : Perform clean-up after a user logged out or loses session
A) Objective This topic explains an implementation strategy that allows bot to remind users of the conversation they started and also to close a conversation that sat idle for too long. Using this implementation, you can also avoid users from staying idle beyond the time configured as the channel session expiry time.
B) View The following is what you will develop in this topic:
Figure 18: Session Clean Up
C) Reference Material Please refer the tech-exchange article to understand complete implementation, link here: https://blogs.oracle.com/mobile/techexchange-how-to-respond-to-user-inactivity-using-the-oracle-web-sdk- messenger-an-implementation-strategy
INT.Q.8 : Optimize longer bot messages displayed in the Oracle Web Messenger
A) Objective This topic explains how you can optimize longer bot messages displayed in the Oracle Web Messenger client to only show the message in full if the user clicks on a link or button.
B) View This is what you will build in this topic:
Figure 19: Read More, Read Less
C) Code Snippet Oracle Web SDK provides a message handler i.e. delegate that can intercept incoming and outgoing messages shared between the client and Oracle Digital Assistant web channel. The SDK provides a delegate property or you could always add delegate explicitly by calling Bots.setDelegate().
The following code in the settings.js is executed after a call to Bots.connect(). It calls a setupDelegate() function from the custom.js file.
// INT.Q.8 : Optimize longer bot messages displayed in the Oracle Web Messenger
// Setup a Delegate. setupDelegate(Bots);
The setupDelegate() function uses a beforeDisplay(message) to call splitParagraph() to create the necessary buttons e.g. READ MORE / READ LESS button.
// INT.Q.8 : Optimize longer bot messages displayed in the Oracle Web Messenger
function setupDelegate(Bots) { // Define a delegate for the Web SDK Bots.setDelegate({ beforeDisplay(message) { if (message.messagePayload.type=='text'){ //Split paragrahps with show-more message.messagePayload.text = splitParagraph(message.messagePayload.text); } return message; } }) }
D) Reference Material Please refer this article for complete implementation: https://blogs.oracle.com/mobile/techexchange-how-to-optimize-the-display-of-long-texts-in-oracle-digital- assistant-web-messenger
INT.Q.9 : Extending Oracle Digital Assistant built-in Styles
A) Objective On a browser like Google Chrome or Firefox you can use Developer tools like inspect to check the styles applied on the chat window. You will notice that there are styles that start with .oda-xxx. These styles can be overridden and supplied in the HTML document or a CSS file.
Make sure you provide this style override in the
tag of the document rather than then tag.In the sample the following style is overridden. This provide a while coloured background.
B) View
Figure 20: Using ODA Styles You can override the background with even an image.
C) Code Snippet This change is in the customUI.css file.
.oda-chat-conversation { background: #ffffff; }
Figure 21: customUI.css code snippet
D) Reference Material The following documentation lists several styles that you can configure and override. https://docs.oracle.com/en/cloud/paas/digital-assistant/use-chatbot/oracle-web.html#GUID-C1CAB5E1-2015-452C- 8F94-DC9381A7E97A
SECTION – III – ADVANCED FEATURES
This section provides answers to questions like how to send a payload to ODA through persistent menu or action buttons, how to alter messages received or sent using the Web SDK delegate, how to provide READ MORE, READ LESS buttons, etc. This section will most likely refer to existing tech exchange articles.
ADV.Q.1 : Using Inline forms to capture use information for simple use cases
A) Objective Inline forms can be presented as HTML content. The content could represent an HTML form that can be very easy for users to fill in. Sending payload (hidden) from Web SDK to ODA. e.g. sending an access token as part of payload. This should not display on the user interface in the chat window. B) View
Figure 22: Inline Forms
C) Code Snippet The skill uses a resource bundle to store an HTML code snippet. Refer to expedite-simple.html
Figure 23: Inline Forms – Resource Bundle This code shows up an inline for the web channel.
Figure 24: Inline Forms - OBotML When the user clicks on the Expedite Request button the following payload is sent to the skill which generates an action “submitRequest”. The hidden: true ensures that the payload is not displayed in the chat window.
Bots.sendMessage({ "messagePayload" :{ "postback": { "variables": { "myCategory": myCategory[myCategory.length-1].value, "myDate": myDate[myDate.length-1].value, "myJustification": myJustification[myJustification.length-1].value }, "action": "submitRequest", "system.state": "openExpediteForm"
}, "text": "Expdite My Request", "type": "postback" }}, {hidden: true } )
ADV.Q.2 : Configure Voice Channel and support various skill voices depending on region
A) Objective Oracle Web SDK can be configured to read bot responses to a user. The language and tone of a bot is usually to match an organization or brand. Likewise, the voice and accent of the text-to-speech (TTS) audio also should match the organization or brand.
B) View The screenshot below shows the sample web client that you can download for this article. After configuring it for your Oracle Web channel, you can start the web client with a double click on the HTML file. Choose a voice from the list and start a conversation with the bot. You can change the voice at any time.
Figure 25: Voice Support
C) Reference Material Please refer the complete article here: https://blogs.oracle.com/mobile/techexchange_dynamically-changing-the-audio-voice-and-accent-used-by-digital- assistant-in-oracle-web-sdk-messenger
ADV.Q.3 : Test Oracle Digital Assistant Web Channels with Client Authentication Enabled
A) Objective This topic will help to create a Local JWT Provider to Test Oracle Digital Assistant Web Channels with Client Authentication Enabled. B) View By default, the client authentication is enabled as shown below:
Figure 26: Enable Client Auth Enabled
C) Reference Material Please refer the below article to test ODA with client authentication enabled: https://blogs.oracle.com/mobile/techexchange-quick-tip%3a-create-a-local-jwt-provider-to-test-oracle-digital- assistant-web-channels-with-client-authentication-enabled
Appendix – API mapping between Old 19.4.1 SDK & Oracle Web SDK 20.6.1
Oracle 20.6.1 Web SDK 19.4.1 Web SDK Description Opens the chat openChat(): void open() widget Closes the chat closeChat(): void close() widget Returns whether isChatOpened(): boolean isOpened() widget is opened Destroys the widget and makes destroy(): void destroy() it disappear
Connects to the connect(): Promise - ODA instance Returns whether the widget is connected to ODA isConnected(): boolean - instance Disconnects from disconnect(): void - ODA instance
Uploads file and sends to chat sendAttachment(file): Promise - server Sends message to sendMessage(message, flags): boolean sendMessage(message) server
updateUser(userDetails: IUserMessage, Update user flags?: IMessageFlags): void updateUser(user) profile
startVoiceRecording(onSpeechRecognition : Function, onSpeechNetworkChange: starts voice Function): Promise - recognition stops voice stopVoiceRecording(): void - recognition
Returns conversation for given user if it getConversationHistory(): object getConversation() exists Returns count of unread messages in getUnreadMessagesCount(): number - the conversation Marks all messages setAllMessagesAsRead(): void markAllAsRead() as read
Sets user input setUserInputMessage(string): void setPredefinedMessage(message) message Sets user input setUserInputPlaceholder(string): void - placeholder text
Sets delegation on conversation to receive callbacks on certain message setDelegate(delegate): void setDelegate(delegate) events
on(name, handler): void on(name, handler) Add event handlers Remove event off(name, handler): void off(name, handler) handlers
setChatBubbleIconHeight(height: string): void -
setChatBubbleIconSize(width: string, height: string): void - setChatBubbleIconWidth(width: string): void - setFont(font: string): void - setFontSize(fontSize: string): void - setHeight(height: string): void - setMessagePadding(padding: string): void - setSize(width: string, height: string): void - setTextColor(color: string): void - setTextColorLight(color: string): void - setWidth(width: string): void -
Conclusion
This article has detailed a list of feature customizations and implementations that the customers can use to implement in their use-case. It will help the existing customers who are migrating to ODA 20.x as well as the customers who are currently using ODA 20.x. The new Oracle Web SDK is much easier to use, requires less coding & has extensive configuration properties and extensibility features.