schema updates

_search-plugins/ubi/data-structures.md

@@ -7,11 +7,16 @@ nav_order: 7
 ---
 
 # Sample client data structures
-The client data structures can be used to create events that follow the [UBI event schema]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/).
+The client data structures can be used to create events that follow the [UBI event schema specification](https://github.com/o19s/opensearch-ubi), 
+which is describedin further detail [here]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/).
 
 The developer provides an implementation for the following functions:
 - `getClientId()`
 - `getQueryId()`
+
+_Optionally_:
+- `getSessionId()`
+- `getPageId()`
 
 Other sample implementations can be found [here](#TODO-clients-link).
 
@@ -21,34 +26,45 @@ Other sample implementations can be found [here](#TODO-clients-link).
  * The following structures help ensure adherence to the UBI event schema
  *********************************************************************************************/
 
+
+
 export class UbiEventData {
-  constructor(type, id=null, description=null, details=null) {
-    this.object_type = type;
+  constructor(object_type, id=null, description=null, details=null) {
+    this.object_id_field = object_type;
     this.object_id = id;
     this.description = description;
     this.object_detail = details;
-
-    //override if using key_field's and values
-    this.key_value = id;
   }
 }
 export class UbiPosition{
   constructor({ordinal=null, x=null, y=null, trail=null}={}) {
     this.ordinal = ordinal;
     this.x = x;
     this.y = y;
-    this.trail = trail;
+    if(trail)
+      this.trail = trail;
+    else {
+      const trail = getTrail();
+      if(trail && trail.length > 0)
+        this.trail = trail;
+    }
   }
 }
 
 
 export class UbiEventAttributes {
   /**
-   * Attributes, other than `object` or `position` should be in the form of
+   * Tries to prepopulate common event attributes
+   * The developer can add an `object` that the user interacted with and
+   *   the site `position` information relevant to the event
+   * 
+   * Attributes, other than `object` or `position` can be added in the form:
    * attributes['item1'] = 1
    * attributes['item2'] = '2'
    *
-   * The object member is reserved for further, relevant object payloads or classes
+   * @param {*} attributes: object with general event attributes 
+   * @param {*} object: the data object the user interacted with
+   * @param {*} position: the site position information
    */
   constructor({attributes={}, object=null, position=null}={}) {
     if(attributes != null){
@@ -60,19 +76,54 @@ export class UbiEventAttributes {
     if(position != null && Object.keys(position).length > 0){
       this.position = position;
     }
+    this.setDefaultValues();
+  }
+
+  setDefaultValues(){
+    try{
+        if(!this.hasOwnProperty('dwell_time') && typeof TimeMe !== 'undefined'){
+          this.dwell_time = TimeMe.getTimeOnPageInSeconds(window.location.pathname);
+        }
+
+        if(!this.hasOwnProperty('browser')){
+          this.browser = window.navigator.userAgent;
+        }
+
+        if(!this.hasOwnProperty('page_id')){
+          this.page_id = window.location.pathname;
+        }
+        if(!this.hasOwnProperty('session_id')){
+          this.session_id = getSessionId();
+        }
+
+        if(!this.hasOwnProperty('page_id')){
+          this.page_id = getPageId();
+        }
+
+        if(!this.hasOwnProperty('position') || this.position == null){
+          const trail = getTrail();
+          if(trail.length > 0){
+            this.position = new UbiPosition({trail:trail});
+          }
+        } 
+        // ToDo: set IP
+    }
+    catch(error){
+      console.log(error);
+    }
   }
 }
 
 
 
 export class UbiEvent {
-  constructor(action_name, {message=null, event_attributes={}, data_object={}}={}) {
+  constructor(action_name, {message_type='INFO', message=null, event_attributes={}, data_object={}}={}) {
     this.action_name = action_name;
-    this.client_id = getClientID();
+    this.client_id = getClientId();
     this.query_id = getQueryId();
     this.timestamp = Date.now();
 
-    this.message_type = 'INFO';
+    this.message_type = message_type;
     if( message )
       this.message = message;
 
@@ -107,6 +158,14 @@ export class UbiEvent {
 # Sample usage
 
 ```js
+export async function logUbiMessage(event_type, message_type, message){
+  let e = new UbiEvent(event_type, {
+    message_type:message_type,
+    message:message
+  });
+  logEvent(e);
+}
+
 export async function logDwellTime(action_name, page, seconds){
   console.log(`${page} => ${seconds}`);
   let e = new UbiEvent(action_name, {

_search-plugins/ubi/schemas.md

@@ -172,7 +172,8 @@ _TODO: How to formalize?  A list of standard ones and then custom ones._
 
 	  (size 256) - optional text message for the log entry.  For example, with a `message_type` of `INFO`, people might expect an informational or debug type text for this field, but a `message_type` of `QUERY`, we would expect the text to be more about what the user is searching on.
 
-{: .warning}  `event_attributes` has dynamic mapping, meaning if events are indexed with many custom fields, the index could bloat quickly with many new fields.
+`event_attributes` has dynamic mapping, meaning if events are indexed with many custom fields, the index could bloat quickly with many new fields.
+{: .warning}  
 
 - `event_attributes`'s structure that describes any important context about the event.  Within it, it has 2 primary structures `position` and `object`, as well as being extensible to add anymore relevant, custom, information about the event can be stored such as timing informaiton, individual user or session information, etc.   
 
@@ -223,3 +224,4 @@ _TODO: How to formalize?  A list of standard ones and then custom ones._
     	  optional text for further data object details
     	     	
       - *extensible fields*: any new fields by any other names in the `object` that one indexes will dynamically expand this schema to that use-case.
+{: .warning}