Merge branch 'main' into query_id_optional

README.md

@@ -105,8 +105,34 @@ In post processing, you can use the Client ID field to connect queries and event
 
 If your user identification is stable, then feel free to use the [Query Request --> Client ID](https://o19s.github.io/ubi/docs/html/query.request.schema.html#client_id) and [Event --> Client ID](https://o19s.github.io/ubi/docs/html/event.schema.html#client_id).  Otherwise, see the above FAQ entry for how to handle it.  The item ID is tracked for an event in the [Event --> Object](https://o19s.github.io/ubi/docs/html/event.schema.html#event_attributes_object) datastructure.
 
+#### How can I correlate private sensitive data with public event tracking?
+
+We often have sensitive data that is returned as part of the search process that changes quickly, and we would not want to expose that information in front end, even hidden!
+
+For example, in ecommerce, we might want to track the margin that is earned on a product, but not pass that data back to the browser, just to collect it later in the events.
+
+To do that, we introduce a cache into our architecture for this sensitive data:
+
+```mermaid
+sequenceDiagram
+    actor Alice
+    Alice ->> Browser: "I want a mobile phone"
+    Browser ->> API: "{user_search_query:mobile phone}"
+    API ->> SearchEngine: "q=mobile phone"
+    SearchEngine ->> UBI_db: Store queryId and SKUs of phones returned to user
+    SearchEngine->>API: Return QueryId and list of mobile phones by SKU with price and profit margin
+    API ->> Cache: Store Margins per Phone under QueryId and SKU
+    API->> Browser: QueryID and list of mobile phones by SKU with price
+    Alice->> Browser: "Click iPhone 15 Pro"
+    Browser->> API: Click Event with SKU and QueryId
+    API->> Cache: Look up Margin based on QueryId and SKU
+    API->> UBI_db: Store queryId and SKU and Margin
+```
 
+Another common reason is to have rich events, but reduce the volume of data passed over the wire to the client.
 
+We sometimes refer to this shortcut architecture as "the Panama Canal", as in taking an extreme shortcut!
+
 
 
 ### 🏫 Learn More

schema/1.0.0/event.schema.json

@@ -22,7 +22,7 @@
         {
           "type": "string",
           "maxLength": 100,
-          "enum": ["click_through", "add_to_cart", "click", "watch", "view", "purchase"]
+          "enum": ["click_through", "add_to_cart", "click", "watch", "view", "purchase", "impression"]
         },
         {
           "type": "string",
@@ -45,12 +45,24 @@
         }
       ]
     },
+    "session_id": {
+      "description": "The session of the user creating the interactions. This allows us to correlate the interactions with the other events created by a service that recognizes session IDs. Can be used to track unique visits for authenticated and anonymous users.",
+      "type": "string",
+      "maxLength": 100,
+      "examples": ["84266fdbd31d4c2c6d0665f7e8380fa3"]
+    },
     "client_id": {
-      "description": "The client issuing the query.  This could be a unique browser, a microservice that performs searches, a crawling bot. If only authenticated users are tracked, then you could use a specific user id here, otherwise you should use something permanent and track user id as an _Additional Property_.",
+      "description": "The client issuing the query.  This could be a unique browser, a microservice that performs searches, a crawling bot.",
       "type": "string",
       "maxLength": 100,
       "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5","quepid-nightly-bot", "BugsBunny::Firefox@0967084"]
     },    
+    "user_id": {
+      "description": "The user ID associated with the person performing the interactions being logged on the site. Can be null/empty in case of an unauthenticated user.",
+      "type": "string",
+      "maxLength": 100,
+      "examples": ["5e3b2a1c-8b7d-4f2e-a3d4-c9b2e1f3a4b5"]
+    },
     "timestamp": {
       "description": "When the event took place.",
       "type": "string",