UBI client data structures

Data structures are used to create events that follow the User Behavior Insights (UBI) event schema specification. For more information about the schema, see UBI index schemas.

You must provide an implementation for the following functions:

  • getClientId()
  • getQueryId()

You can also optionally provide an implementation for the following functions:

  • getSessionId()
  • getPageId()

The following JavaScript structures can be used as a starter implementation to serialize UBI events into schema-compatible JSON:

  1. /*********************************************************************************************
  2.  * Ubi Event data structures
  3.  * The following structures help ensure adherence to the UBI event schema
  4.  *********************************************************************************************/
  8. export class UbiEventData {
  9.   constructor(object_type, id=null, description=null, details=null) {
  10.     this.object_id_field = object_type;
  11.     this.object_id = id;
  12.     this.description = description;
  13.     this.object_detail = details;
  14.   }
  15. }
  16. export class UbiPosition{
  17.   constructor({ordinal=null, x=null, y=null, trail=null}={}) {
  18.     this.ordinal = ordinal;
  19.     this.x = x;
  20.     this.y = y;
  21.     if(trail)
  22.       this.trail = trail;
  23.     else {
  24.       const trail = getTrail();
  25.       if(trail && trail.length > 0)
  26.         this.trail = trail;
  27.     }
  28.   }
  29. }
  32. export class UbiEventAttributes {
  33.   /**
  34.    * Tries to prepopulate common event attributes
  35.    * The developer can add an `object` that the user interacted with and
  36.    *   the site `position` information relevant to the event
  37.    * 
  38.    * Attributes, other than `object` or `position` can be added in the form:
  39.    * attributes['item1'] = 1
  40.    * attributes['item2'] = '2'
  41.    *
  42.    * @param {*} attributes: object with general event attributes 
  43.    * @param {*} object: the data object the user interacted with
  44.    * @param {*} position: the site position information
  45.    */
  46.   constructor({attributes={}, object=null, position=null}={}) {
  47.     if(attributes != null){
  48.       Object.assign(this, attributes);
  49.     }
  50.     if(object != null && Object.keys(object).length > 0){
  51.       this.object = object;
  52.     }
  53.     if(position != null && Object.keys(position).length > 0){
  54.       this.position = position;
  55.     }
  56.     this.setDefaultValues();
  57.   }
  59.   setDefaultValues(){
  60.     try{
  61.         if(!this.hasOwnProperty('dwell_time') && typeof TimeMe !== 'undefined'){
  62.           this.dwell_time = TimeMe.getTimeOnPageInSeconds(window.location.pathname);
  63.         }
  65.         if(!this.hasOwnProperty('browser')){
  66.           this.browser = window.navigator.userAgent;
  67.         }
  69.         if(!this.hasOwnProperty('page_id')){
  70.           this.page_id = window.location.pathname;
  71.         }
  72.         if(!this.hasOwnProperty('session_id')){
  73.           this.session_id = getSessionId();
  74.         }
  76.         if(!this.hasOwnProperty('page_id')){
  77.           this.page_id = getPageId();
  78.         }
  80.         if(!this.hasOwnProperty('position') || this.position == null){
  81.           const trail = getTrail();
  82.           if(trail.length > 0){
  83.             this.position = new UbiPosition({trail:trail});
  84.           }
  85.         } 
  86.         // ToDo: set IP
  87.     }
  88.     catch(error){
  89.       console.log(error);
  90.     }
  91.   }
  92. }
  96. export class UbiEvent {
  97.   constructor(action_name, {message_type='INFO', message=null, event_attributes={}, data_object={}}={}) {
  98.     this.action_name = action_name;
  99.     this.client_id = getClientId();
  100.     this.query_id = getQueryId();
  101.     this.timestamp = Date.now();
  103.     this.message_type = message_type;
  104.     if( message )
  105.       this.message = message;
  107.     this.event_attributes = new UbiEventAttributes({attributes:event_attributes, object:data_object});
  108.   }
  110.   /**
  111.    * Use to suppress null objects in the json output
  112.    * @param key
  113.    * @param value
  114.    * @returns
  115.    */
  116.   static replacer(key, value){
  117.     if(value == null || 
  118.       (value.constructor == Object && Object.keys(value).length === 0)) {
  119.       return undefined;
  120.     }
  121.     return value;
  122.   }
  124.   /**
  125.    *
  126.    * @returns json string
  127.    */
  128.   toJson() {
  129.     return JSON.stringify(this, UbiEvent.replacer);
  130.   }
  131. }

copy

Sample usage

  1. export function logUbiMessage(event_type, message_type, message){
  2.   let e = new UbiEvent(event_type, {
  3.     message_type:message_type,
  4.     message:message
  5.   });
  6.   logEvent(e);
  7. }
  9. export function logDwellTime(action_name, page, seconds){
  10.   console.log(`${page} => ${seconds}`);
  11.   let e = new UbiEvent(action_name, {
  12.     message:`On page ${page} for ${seconds} seconds`,
  13.     event_attributes:{
  14.       session_id: getSessionId()},
  15.       dwell_seconds:seconds
  16.       },
  17.     data_object:TimeMe
  18.   });
  19.   logEvent(e);
  20. }
  22. /**
  23.  * ordinal is the number within a list of results
  24.  * for the item that was clicked
  25.  */ 
  26. export function logItemClick(item, ordinal){
  27.   let e = new UbiEvent('item_click', {
  28.     message:`Item ${item['object_id']} was clicked`,
  29.     event_attributes:{session_id: getSessionId()},
  30.     data_object:item,    
  31.   });
  32.   e.event_attributes.position.ordinal = ordinal;
  33.   logEvent(e);
  34. }
  36. export function logEvent( event ){
  37.   // some configured http client 
  38.   return client.index( index = 'ubi_events', body = event.toJson());
  39. }

copy