Revamping documentations to reflect updates.

epugh · epugh · commit 6ba8662870d0 · 2024-11-23T08:04:26.000-05:00
UBI has evolved since it was first released in May 2024.  This is an update of the documentation.  We have introduced an explicit JS client, so we can streamline the documentation by referencing the deployed document.
diff --git a/_search-plugins/ubi/data-structures.md b/_search-plugins/ubi/data-structures.md
diff --git a/_search-plugins/ubi/index.md b/_search-plugins/ubi/index.md
@@ -11,16 +11,17 @@ redirect_from:
 **Introduced 2.15**
 {: .label .label-purple }
 
-**References UBI Specification 1.0.0**
+**References UBI Specification 1.2.0**
 {: .label .label-purple }
 
-User Behavior Insights (UBI) is a plugin that captures client-side events and queries for the purposes of improving search relevance and the user experience.
-It is a causal system, linking a user's query to all of their subsequent interactions with your application until they perform another search.
+User Behavior Insights (UBI) is a project for capturing client-side events and queries for the purposes of improving search relevance and the user experience.
+It is a *causal* system, linking a user's query to all of their subsequent interactions with your application until they perform another search.
+This differs from many systems that infer the linking of search to events through *chronological* sequence.
 
 UBI includes the following elements:
 * A machine-readable [schema](https://github.com/o19s/ubi) that faciliates interoperablity of the UBI specification.
 * An OpenSearch [plugin](https://github.com/opensearch-project/user-behavior-insights) that facilitates the storage of client-side events and queries.
-* A client-side JavaScript [example reference implementation]({{site.url}}{{site.baseurl}}/search-plugins/ubi/data-structures/) that shows how to capture events and send them to the OpenSearch UBI plugin.
+* A client-side JavaScript [reference implementation](https://github.com/opensearch-project/user-behavior-insights/tree/main/ubi-javascript-collector/ubi.js) that shows how to capture searches and events.
 
 <!-- vale off -->
 
@@ -30,7 +31,8 @@ The UBI documentation is organized into two categories: *Explanation and referen
 
 | Link | Description |
 | :--------- | :------- |
-| [UBI Request/Response Specification](https://github.com/o19s/ubi/) | The industry-standard schema for UBI requests and responses. The current version references UBI Specification 1.0.0.  |
+| [UBISearch.dev](https://UBISearch.dev) | The User Behavior Insights community website.  |
+| [UBI Request/Response Specification](https://github.com/o19s/ubi/) | The industry-standard schema for UBI requests and responses. The current version references UBI Specification 1.2.0.  |
 | [UBI index schema]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/) | Documentation on the individual OpenSearch query and event stores. |
 
 
@@ -39,7 +41,7 @@ The UBI documentation is organized into two categories: *Explanation and referen
 | Link | Description |
 | :--------- | :------- |
 | [UBI plugin](https://github.com/opensearch-project/user-behavior-insights) | How to install and use the UBI plugin. |
-| [UBI client data structures]({{site.url}}{{site.baseurl}}/search-plugins/ubi/data-structures/)  | Sample JavaScript structures for populating the event store. |
+| [UBI JavaScript Collector]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-javascript-collector/)  | Clientside JavaScript library to capture events. |
 | [Example UBI query DSL queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/dsl-queries/)  | How to write queries for UBI data in OpenSearch query DSL. |
 | [Example UBI SQL queries]({{site.url}}{{site.baseurl}}/search-plugins/ubi/sql-queries/)  | How to write analytic queries for UBI data in SQL. |
 | [UBI dashboard tutorial]({{site.url}}{{site.baseurl}}/search-plugins/ubi/ubi-dashboard-tutorial/) | How to build a dashboard containing UBI data. |
diff --git a/_search-plugins/ubi/schemas.md b/_search-plugins/ubi/schemas.md
@@ -16,8 +16,8 @@ The User Behavior Insights (UBI) data collection process involves tracking and r
 
 For UBI to function properly, the connections between the following fields must be consistently maintained within an application that has UBI enabled:
 
-- [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN code of a book, such as `978-3-16-148410-0`.
-- [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` values of the _hits_ returned by the user's query.  
+- [`object_id`](#object_id) represents an ID for whatever object the user receives in response to a query. For example, if you search for books, it might be an ISBN number for a book, such as `978-3-16-148410-0`.
+- [`query_id`](#query_id) is a unique ID for the raw query language executed and the `object_id` maps to the primary identifier of the _hits_ returned by the user's query.  
 - [`client_id`](#client_id) represents a unique query source. This is typically a web browser used by a unique user.
 - [`object_id_field`](#object_id_field) specifies the name of the field in your index that provides the `object_id`. For example, if you search for books, the value might be `isbn_code`.
 - [`action_name`](#action_name), though not technically an ID, specifies the exact user action (such as `click`, `add_to_cart`, `watch`, `view`, or `purchase`) that was taken (or not taken) for an object with a given `object_id`.
@@ -138,11 +138,11 @@ All underlying query information and results (`object_ids`) are stored in the `u
 
 The `ubi_queries` index [schema](https://github.com/OpenSearch-project/user-behavior-insights/tree/main/src/main/resources/queries-mapping.json) includes the following fields:
 
-- `timestamp` (events and queries): A UNIX timestamp indicating when the query was received.
+- `timestamp` (events and queries): A ISO 8601 formatted timestamp indicating when the query was received.
 
-- `query_id` (events and queries): The unique ID of the query provided by the client or generated automatically. Different queries with the same text generate different `query_id` values. 
+- `query_id` (events and queries): The unique ID of the query provided by the client or generated by the search engine. Different queries with the same text generate different `query_id` values. 
 	
-- `client_id` (events and queries): A user/client ID provided by the client application.
+- `client_id` (events and queries): A client ID provided by the client application.
 
 - `query_response_objects_ids` (queries): An array of object IDs. An ID can have the same value as the `_id`, but it is meant to be the externally valid ID of a document, item, or product.
 
@@ -169,7 +169,7 @@ The following are the predefined, minimal fields in the `ubi_events` index:
  <p id="query_id"> </p>
 
 - `query_id` (size 100): The unique identifier of a query, which is typically a UUID but can be any string.
- The `query_id` is either provided by the client or generated at index time by the UBI plugin. The `query_id` values in both the **UBI queries** and **UBI events** indexes must be consistent.
+ The `query_id` is either provided by the client or generated at query time by the UBI plugin. The `query_id` values in both the **UBI queries** and **UBI events** indexes must be consistent.
 
 <p id="client_id"> </p>
 
@@ -193,18 +193,12 @@ The following are the predefined, minimal fields in the `ubi_events` index:
  
    - `event_attributes.position.ordinal`: Tracks the list position that a user can select (for example, selecting the third element can be described as `event{onClick, results[4]}`).
 
-    - `event_attributes.position.{x,y}`: Tracks x and y values defined by the client.
-
-    - `event_attributes.position.page_depth`: Tracks the page depth of the results.
-
-    - `event_attributes.position.scroll_depth`: Tracks the scroll depth of the page results.
-
-    - `event_attributes.position.trail`: A text field that tracks the path/trail that a user took to get to this location.
-  
+    - `event_attributes.position.xy.{x,y}`: Tracks x and y values defined by the client.
+    
   - `event_attributes.object`: Contains identifying information about the object returned by the query (for example, a book, product, or post).
    The `object` structure can refer to the object by internal ID or object ID. The `object_id` is the ID that links prior queries to this object. This field comprises the following subfields:
   
-    - `event_attributes.object.internal_id`: A unique ID that OpenSearch can use to internally index the object, for example, the `_id` field in the indexes.
+    - `event_attributes.object.internal_id`: The unique ID that OpenSearch uses to internally index the object, for example, the `_id` field in the indexes.
 
       <p id="object_id">
 
@@ -214,9 +208,9 @@ The following are the predefined, minimal fields in the `ubi_events` index:
 
       <p id="object_id_field">
          
-    - `event_attributes.object.object_id_field`: Indicates the type/class of the object and the name of the search index field that contains the `object_id`.  
+    - `event_attributes.object.object_id_field`: Indicates the type/class of the object and the name of the search index field that contains the `object_id` such as `ssn`, `isbn`, or `ean`.  
 
-    - `event_attributes.object.description`: An optional description of the object.
+    - `event_attributes.object.object_type`: An optional readable version of the type/class of the object. For a social e-commerce site, these could include product, user, post, comment and so on.
 
     - `event_attributes.object.object_detail`: Optional additional information about the object.
           
diff --git a/_search-plugins/ubi/ubi-javascript-collector.md b/_search-plugins/ubi/ubi-javascript-collector.md
@@ -0,0 +1,81 @@
+---
+layout: default
+title: UBI Javascript Collector
+parent: User Behavior Insights
+has_children: false
+nav_order: 10
+---
+
+# UBI Javascript Collector
+
+UBI comes with a very basic JavaScript client that manages the life cycle of the `query_id` for a specific search and can create UBI Event data structures and store them for specific actions.
+
+For more information about the schema, see [UBI index schemas]({{site.url}}{{site.baseurl}}/search-plugins/ubi/schemas/).
+
+We recommend that you refer to the client as a starting point for your own specific needs.
+
+## Installation
+
+The client comes as a single file `ubi.js` and only has a dependency on the `axios` library.  Download it from https://github.com/opensearch-project/user-behavior-insights/tree/main/ubi-javascript-collector.
+
+Reference the events and create the client via:
+
+```js
+import { UbiEvent } from './ubi';
+import { UbiEventAttributes } from './ubi'
+import { UbiClient } from './ubi'
+
+const ubiClient = new  UbiClient('http://localhost:9200');
+```
+
+
+## Creating an Event 
+
+This code snippet is to track adding an item to a shopping cart in an e-commerce application. It utilizes the `UbiEvent` and `UbiEventAttributes` class to encapsulate event details, which can then be sent to the tracking system.
+```js
+var event = new UbiEvent(
+    'add_to_cart', 
+    client_id, 
+    session_id, 
+    getQueryId(), 
+    new UbiEventAttributes('product', item.primary_ean, item.title, item), 
+    item.title + ' (' + item.id + ')'
+);
+```
+
+### Parameters
+
+1. **Event Name**: 
+   - `'add_to_cart'` - This string indicates the type of event being tracked.
+
+2. **Client ID**: 
+   - `client_id` - A variable that holds the unique identifier for the client. This helps in distinguishing between different users or sessions.
+
+3. **Session ID**: 
+   - `session_id` - A variable that contains the unique identifier for the user session. This is used to track user interactions within a specific session.
+
+4. **Query ID**: 
+   - `getQueryId()` - A function call that retrieves the current query ID, which may represent a specific search or interaction context.
+
+5. **UbiEventAttributes**: 
+   - This is an instance of the `UbiEventAttributes` class, which encapsulates additional details about the event:
+     - **Type**: 
+       - `'product'` - Specifies that the attribute type is related to a product.
+     - **Primary EAN**: 
+       - `item.primary_ean` - This is the product's unique identifier in EAN format.
+     - **Title**: 
+       - `item.title` - The name or description of the product.
+     - **Item**: 
+       - `item` - The complete product object containing all relevant details.
+
+6. **Event Label**: 
+   - `item.title + ' (' + item.id + ')'` - This creates a descriptive label for the event that includes the product title and its unique identifier (ID).
+   
+   
+## Tracking the Event 
+
+Sending the event to the backend is as simple as:
+
+```js
+ubiClient.trackEvent(event);
+```
