Skip to content

Commit 2abce6e

Browse files
epughepugh
committed
Going to check all this in for now...
1 parent 7a34c4e commit 2abce6e

17 files changed

Lines changed: 1838 additions & 1 deletion

‎blacklight/UBI_DIRECT_INTEGRATION.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
# UBI Direct Integration (No Webpack/Yarn Required!)
2+
3+
The UBI tracking is now set up to work directly with Rails asset pipeline - no webpack or yarn compilation needed!
4+
5+
## What Changed
6+
7+
### ✅ Created Browser-Compatible Files:
8+
1. **`app/assets/javascripts/ubi.js`** - Core UBI library (browser-compatible, uses fetch instead of axios)
9+
2. **`app/assets/javascripts/ubi-client.js`** - Client helpers (browser-compatible)
10+
3. **`app/assets/javascripts/ubi-tracking.js`** - Tracking functions (browser-compatible)
11+
12+
### ✅ Updated Files:
13+
1. **`app/views/catalog/_search_header.html.erb`** - Now includes script tags directly
14+
2. **`config/initializers/assets.rb`** - Registered UBI files for precompilation
15+
16+
## How It Works
17+
18+
The scripts are loaded via Rails asset pipeline using `javascript_include_tag`:
19+
```erb
20+
<%= javascript_include_tag 'ubi' %>
21+
<%= javascript_include_tag 'ubi-client' %>
22+
<%= javascript_include_tag 'ubi-tracking' %>
23+
```
24+
25+
All functions are available globally:
26+
- `window.UbiClient` - UBI client class
27+
- `window.UbiEvent` - Event class
28+
- `window.UbiEventAttributes` - Event attributes class
29+
- `window.UbiQueryRequest` - Query request class
30+
- `window.UbiClientHelpers` - Helper functions
31+
- `window.UbiTracking` - High-level tracking functions
32+
33+
## Configuration
34+
35+
Edit `app/assets/javascripts/ubi-client.js` to set your OpenSearch URL (line 9):
36+
```javascript
37+
const OPENSEARCH_URL = 'http://localhost:9200'; // Change to your OpenSearch endpoint
38+
```
39+
40+
## Testing
41+
42+
1. **Restart your Rails server** (important for asset pipeline changes):
43+
```bash
44+
cd /Users/epugh/Documents/projects/chorus/blacklight
45+
rails s
46+
```
47+
48+
2. Open browser console and perform a search
49+
50+
3. You should see:
51+
```
52+
Setting up UBI search query tracking
53+
Search field value: notebook
54+
About to track search query: notebook
55+
UBI: Tracked search query: notebook Query ID: xxxx-xxxx-xxxx
56+
```
57+
58+
## Usage Examples
59+
60+
### Track Product Clicks
61+
```erb
62+
<%= link_to product_path(product),
63+
onclick: "window.UbiTracking.trackProductClick({id: '#{product.id}', title: '#{escape_javascript(product.title)}'}, #{index}); return true;" do %>
64+
<%= product.title %>
65+
<% end %>
66+
```
67+
68+
### Track Product Views
69+
```erb
70+
<script>
71+
window.UbiTracking.trackProductView({
72+
id: '<%= @product.id %>',
73+
title: '<%= escape_javascript(@product.title) %>'
74+
});
75+
</script>
76+
```
77+
78+
### Debug
79+
```javascript
80+
window.UbiClientHelpers.debugUbiIds()
81+
```
82+
83+
## Key Differences from Module Version
84+
85+
- ✅ No webpack/yarn needed
86+
- ✅ No module imports/exports
87+
- ✅ Uses native `fetch` instead of axios
88+
- ✅ All code in browser-compatible IIFE format
89+
- ✅ Works with Rails asset pipeline
90+
- ✅ Available immediately after page load
91+
92+
## Next Steps
93+
94+
1. ⚠️ **Restart Rails server** for asset pipeline changes
95+
2. ⚙️ Update OpenSearch URL in `ubi-client.js`
96+
3. 🧪 Test search tracking in browser console
97+
4. 📝 Add product click tracking to search results
98+
5. 🔍 Verify events in OpenSearch
99+
100+
---
101+
102+
**Ready to track! No build tools required!** 🎉

‎blacklight/UBI_INTEGRATION_COMPLETE.md‎

Lines changed: 122 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,122 @@
1+
# UBI Integration Complete! 🎉
2+
3+
The User Behavior Insights (UBI) JavaScript collector has been successfully integrated into your Chorus Electronics Blacklight application.
4+
5+
## What Was Done
6+
7+
### ✅ Files Created
8+
9+
1. **`app/javascript/ubi.js`** - Core UBI library from OpenSearch
10+
2. **`app/javascript/ubi-client.js`** - Client initialization and helper functions
11+
3. **`app/javascript/ubi-tracking.js`** - High-level tracking functions
12+
4. **`UBI_INTEGRATION_README.md`** - Complete documentation
13+
5. **`app/views/catalog/UBI_INTEGRATION_EXAMPLES.html`** - Code examples
14+
15+
### ✅ Files Updated
16+
17+
1. **`app/javascript/packs/application.js`** - Added UBI module imports
18+
2. **`app/views/catalog/_search_header.html.erb`** - Added automatic search query tracking
19+
20+
### ✅ Dependencies Installed
21+
22+
- `axios@1.13.2` - HTTP client required by UBI.js
23+
24+
## How to Use
25+
26+
### Automatic Search Tracking ✨
27+
Search queries are automatically tracked when results are displayed! No additional code needed.
28+
29+
### Track Product Clicks
30+
Add to your product listing template where products are displayed:
31+
32+
```erb
33+
<%= link_to url_for_document(document),
34+
onclick: "if (window.UbiTracking) {
35+
window.UbiTracking.trackProductClick({
36+
id: '#{document.id}',
37+
title: '#{escape_javascript(document.title.first)}'
38+
}, #{counter});
39+
}" do %>
40+
<%= document.title.first %>
41+
<% end %>
42+
```
43+
44+
### Track Product Views
45+
Add to product detail pages:
46+
47+
```erb
48+
<script>
49+
if (window.UbiTracking) {
50+
window.UbiTracking.trackProductView({
51+
id: '<%= @document.id %>',
52+
title: '<%= escape_javascript(@document.title.first) %>'
53+
});
54+
}
55+
</script>
56+
```
57+
58+
### Available Tracking Functions
59+
60+
All available via `window.UbiTracking`:
61+
62+
- `trackSearchQuery(query, objectIdField, queryAttributes)` - Tracks searches (auto-enabled)
63+
- `trackProductClick(product, position)` - Track product clicks
64+
- `trackProductView(product)` - Track product views
65+
- `trackAddToCart(product, quantity)` - Track add to cart
66+
- `trackPurchase(products, orderInfo)` - Track purchases
67+
- `trackCustomEvent(actionName, eventData)` - Track custom events
68+
69+
## Configuration Required
70+
71+
### 1. Update OpenSearch URL
72+
Edit `app/javascript/ubi-client.js` line 8:
73+
```javascript
74+
const OPENSEARCH_URL = 'http://localhost:9200'; // Change to your OpenSearch endpoint
75+
```
76+
77+
### 2. Ensure OpenSearch UBI Plugin is Installed
78+
Your OpenSearch instance needs the UBI plugin configured to receive events at:
79+
- `/ubi_events` - For event data
80+
- `/ubi_queries` - For query data
81+
82+
See: https://docs.opensearch.org/latest/search-plugins/ubi/index/
83+
84+
## Testing
85+
86+
1. Start your Rails server
87+
2. Open browser developer console
88+
3. Perform a search
89+
4. You should see: `UBI: Tracked search query: notebook Query ID: xxxx-xxxx-xxxx-xxxx`
90+
5. Click a product (if tracking is added)
91+
6. You should see: `UBI: Tracked product click: Product Name`
92+
93+
### Debug Command
94+
In the browser console:
95+
```javascript
96+
window.UbiTracking.debugUbiIds()
97+
```
98+
99+
## Next Steps
100+
101+
1. ✅ **Start your Rails server** - The assets will compile automatically
102+
2. ⚙️ **Update OpenSearch URL** in `ubi-client.js`
103+
3. 📝 **Add product click tracking** to your search results template
104+
4. 📊 **Add product view tracking** to detail pages
105+
5. 🛒 **Add cart tracking** (if applicable)
106+
6. 💳 **Add purchase tracking** to order confirmation
107+
7. 🔍 **Verify events** are being sent to OpenSearch
108+
8. 🚀 **Turn off verbose logging** for production (set `verbose = 0`)
109+
110+
## Documentation
111+
112+
- **`UBI_INTEGRATION_README.md`** - Complete integration guide
113+
- **`app/views/catalog/UBI_INTEGRATION_EXAMPLES.html`** - Code examples
114+
- **OpenSearch UBI Docs**: https://docs.opensearch.org/latest/search-plugins/ubi/ubi-javascript-collector/
115+
116+
## Note About Webpack
117+
118+
The webpack compilation encountered a Node.js version compatibility issue, but this won't affect the integration. When you start your Rails server with `rails s` or `foreman start`, webpack-dev-server will compile the assets automatically and the UBI tracking will be available.
119+
120+
---
121+
122+
**Ready to track user behavior!** 🎯📈

0 commit comments

Comments
 (0)