12 Bots Analytics

Use the Analytics Collector API to send events to an analytics app via a Bots custom component.

Adding Analytics to the PizzaBot Sample Bot

OMCe platform APIs, including the Analytics API, are available to a custom component via the conversation.oracleMobile object.

Use conversation.oracleMobile.analytics.postEvent() to send data about your bot and how it's being used to OMCe Analytics. You just need to make sure that the OMCe Analytics application is associated with the backend that's running the custom component, and that you configure a custom schema for the Analytics application to handle the data.

To demonstrate how to add Analytics to a bot, we'll use the PizzaBot sample bot.

Setting up the PizzaBot Analytics Application

Set up the Analytics application in OMCe Analytics and attach it to the backend that runs the custom component.

1. Open OMCe Analytics and create an application with the name PizzaAnalytics.
2. Add a new property of type Metric, and give it the name age.

   Note:

   For more information about custom schemas, see Custom Schemas in Developing Applications with Oracle Mobile Cloud Enterprise.
3. Click Settings then click Application and copy the Application ID.
4. Open OMCe Mobile Apps and open the backend that runs the custom components for the PizzaBot bot.
5. Click Settings and in the Applications ID field, paste the Application ID that you copied earlier.

After the Analytics application and the backend are configured, set up your custom code to post an event to the Analytics application. You do this by modifying the existing age_checker.js custom component code.

Setting up the PizzaBot Custom Component

Add analytics to the AgeChecker custom component by modifying the code in age_checker.js. You add code that takes the data that comes from the bot, and uses the Analytics API to send it to the analytics application.

1. Open OMCe and go to Mobile Apps then APIs.
2. Open the API that contains the custom components that the PizzaBot sample bot uses. If you're not sure which API it is, open the backend that runs the custom components for the bot, and expand the Dependencies section where you'll see the API that contains the custom components.
3. Click Implementation. When the Implementation panel opens click bots_samples and save the downloaded api_implementation.zip file in a convenient location on your hard drive. Keep this page open because you'll need it in a later step when you upload the modified implementation.
4. Extract the files from api_implementation.zip and open api_implementation/sample_bots/pizza/age_checker.js.
5. Add the following two functions, postEvent and postCustomAnalyticEvents, to the bottom of age_checker.js:

   /**
    * Posts a single custom analytics event, with a single custom property.
    * @param {object} analytics the custom code SDK analytics object,
       usually obtained from conversation.oracleMobile.analytics
    * @param {string} eventName the name of the custom event
    * @param {string} customProperty the name of the custom property
    * @param {string} customValue the value of the custom property
    * @returns {object} a Promise
    */
   var postEvent = function (analytics, eventName, customProperty, customValue) {
       const timestamp = (new Date()).toISOString();
       return postCustomAnalyticEvents(
           analytics,
           {
               "name": eventName,
               "type": "custom",
               "timestamp": timestamp,
               "properties": { [customProperty] : customValue.toString() } // custom values must be passed as String
           },
           timestamp
       );
   };
   
   /**
    * Posts custom analytics events.
    * @param {object} analytics the custom code SDK analytics object,
       usually obtained from conversation.oracleMobile.analytics
    * @param {object} customEvents either a single custom event 
       object or an Array of custom event objects
    * @param {string} sessionStartTimestamp ISO formated String
       representation of a Date object
    * @param {string} [sessionEndTimestamp] ISO formated String
       representation of a Date object
    * @returns {object} a Promise
    */
   var postCustomAnalyticEvents = function (analytics, customEvents, 
                                            sessionStartTimestamp, sessionEndTimestamp ) {
       const events = [];
       events.push(
           {
               "name": "sessionStart",
               "type": "system",
               "timestamp": sessionStartTimestamp
           }
       );
       Array.isArray(customEvents) ? Array.prototype.push.apply(events, customEvents) : events.push(customEvents);
       events.push(
           {
               name: "sessionEnd",
               type: "system",
               "timestamp": sessionEndTimestamp ? sessionEndTimestamp : sessionStartTimestamp
           }
       );
       return analytics.postEvent(events);
   };
   

   Tip:

   The functions are generic enough that you can use them unchanged in any custom code, not just the PizzaBot bot.
6. Next, modify the invoke method in age_checker.js to call the postEvent function that you just added. Notice the use of conversation.oracleMobile.analytics in postEvent().

   invoke: (conversation, done) => {
       // Parse a number out of the incoming message
       const text = conversation.text();
       const matches = text.match(/\d+/);
       var age = 0;
       if (matches) {
           age = matches[0];
       }
   
       console.info('AgeChecker: using age=' + age);
   
       // Set action based on age check
       conversation.transition( age >= 18 ? 'allow' : 'block' );
   
       // Original code until here. Analytics logic below.
   
       // captures age in a custom analytics event.
       postEvent(
           conversation.oracleMobile.analytics,
           "pizzaEvent",
           "age",
           age
       ).then(
           function (result) {
               done();
           },
           function (error) {
               console.warn('AgeChecker: error posting analytics.',
                             error.statusCode, error.error);
               done();
           }
       );
   }

7. Zip up the api_implementation folder. Make sure the zip file has the same internal structure as the one that you downloaded.
8. On the Implementation panel, click Upload an implementation archive and upload the new api_implementation.zip file.

After the implementation is successfully uploaded, the bot is ready for testing.