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.