Adding client-derived variables to articles

Follow these steps to add client content dynamically within articles.

1. In the Bold360 AI Console, create an article that contains variables with values that can be obtained within the browser inside double square brackets. For example: [[USER_TIME]] or [[SCREEN_RESOLUTION]]. The variables in this example are bold, but that is not required. Publish the article so that it is available to your widget.

   
   

   
   
   
   Note: The variables can be uppercase or lowercase, but they are case sensitive. The square brackets are important to indicate that these are evaluated later.

2. Go to the registerClientEntities method in the Bold360 AI Web API & SDK reference.
   Note: Notice that this method is only available to widgets running in "conversational" mode. Because embedded widgets always run in "search" mode, this method is not available to embedded widgets. Typically, floating widgets are run in conversational mode. If you use a floating widget in search mode, this method is not available.

3. Use an editor to open an HTML page that contains a floating widget.
4. Paste the following code into the <script> that initializes the floating widget.

   nanorep.floatingWidget.on('load', function() {
      this.api.conversation.registerClientEntities({
         USER_TIME: function() {
            return ({
               kind: "USER_TIME",
               type: "text",
               value: "test1"
            });
         }
      });
   });

   The example in the Web API & SDK reference is longer and shows that you can register arrays and other types of information.

5. Test your web page. Remember to refresh the page and type RESET in the widget to get the current behavior. Then type the title of your article and select that option.

   
   

   
   
   

6. To see how the client provides values for insertion into articles supplied by the server, open the Developer Tools (the Chrome tools are shown below, but other tools are similar) and examine the following:
   1. Go to the Network page and select the Headers tab.
   2. In the list of API requests sent, select the create request. The Request URL shows that the /api/conversation/v2/create REST API was called.
   3. In the Query String Parameters, you'll see that only the name (not the value) of the client entity was sent to the server when the conversation was created.

      
      

      
      
      

   4. Next, select the statement request, which called the /api/conversation/v1/statement REST API. In the Form Data section, you'll see the name, type, and value of the USER_TIME variable. You can see the value integrated into the retrieved article in the Preview and Response tabs.

      
      

      
      
      

7. Modify the code as follows to set USER_TIME to the customer's current time. The following code also defines the SCREEN_RESOLUTION variable using screen information that is available only through the customer's browser.

   nanorep.floatingWidget.on('load', function() {
     this.api.conversation.registerClientEntities({
   	  USER_TIME: function() {
   		return ({
   		  kind: "USER_TIME",
   		  type: "text",
   		  value: new Date().toLocaleString()
   		});
   	  },
   	  SCREEN_RESOLUTION: function() {
   		return ({
   		  kind: "SCREEN_RESOLUTION",
   		  type: "text",
   		  value: screen.width + "x" + screen.height
   		});
   	  }
     });
   });
   

8. Test your web page and call up the article that contains the client entities. You should see your current date and time and your screen resolution. If the variables in your article are in bold, they will also be shown in bold here.

   
   

   
   
   

9. But, notice that if you call up the article again, the time does not change. The variable was set when the script ran in your browser. To fix this, make the following addition to change the lifecycle of the entity:

   	  USER_TIME: function() {
   	     return ({
   	        kind: "USER_TIME",
   	        type: "text",
   	        value: new Date().toLocaleString(),
   	        lifecycle: "intent"
   	  });

   Now, the time should be updated every time you reload the article.

   Tip: The example in the Web API & SDK reference also shows that you can use the JavaScript Promise syntax when returning the results of an asynchronous call. The following example uses a 3-second timeout, but can be modified to use an asynchronous call:

            SCREEN_RESOLUTION: function() {
               return new Promise(function(resolve) {
                  setTimeout(function() {
                     resolve({
                        kind: "SCREEN_RESOLUTION",
                        type: "text",
                        value: screen.width + "x" + screen.height
                     });
                  }, 3000);
               });
            }