wow, chrome-extension MUCH improved - websockets
This commit is contained in:
cottongin
213
chrome-extension/README.md
Normal file
213
chrome-extension/README.md
Normal file
@@ -0,0 +1,213 @@
|
||||
# Jackbox Chat Tracker Chrome Extension
|
||||
|
||||
A Chrome extension for tracking Jackbox game votes (`thisgame++` and `thisgame--`) from Kosmi chat.
|
||||
|
||||
## Features
|
||||
|
||||
- ✅ Tracks `thisgame++` and `thisgame--` votes in Kosmi chat
|
||||
- ✅ Records username, full message, and UTC timestamp
|
||||
- ✅ Case-insensitive matching (works with `THISGAME++`, `ThisGame--`, etc.)
|
||||
- ✅ Matches votes anywhere in the message
|
||||
- ✅ Exports data as JSON in the format expected by the Jackbox Game Picker app
|
||||
- ✅ Real-time vote tracking with live updates
|
||||
- ✅ Simple, intuitive interface
|
||||
|
||||
## Installation
|
||||
|
||||
1. Open Chrome and navigate to `chrome://extensions/`
|
||||
2. Enable "Developer mode" in the top right
|
||||
3. Click "Load unpacked"
|
||||
4. Select the `chrome-extension` folder
|
||||
5. The extension is now installed!
|
||||
|
||||
## Usage
|
||||
|
||||
### Starting a Tracking Session
|
||||
|
||||
1. Navigate to a Kosmi room: `https://app.kosmi.io/room/...`
|
||||
2. Click the extension icon in your browser toolbar
|
||||
3. Click "Start Tracking"
|
||||
4. The extension will now monitor chat for votes
|
||||
|
||||
### Viewing Votes
|
||||
|
||||
- The popup shows all recorded votes in real-time
|
||||
- Each vote displays:
|
||||
- Username
|
||||
- Full message text
|
||||
- Timestamp (in your local timezone)
|
||||
- Vote type (positive/negative indicated by color)
|
||||
|
||||
### Exporting Data
|
||||
|
||||
1. Click "Export JSON" to download votes
|
||||
2. The file format matches the Jackbox Game Picker import format:
|
||||
```json
|
||||
[
|
||||
{
|
||||
"username": "Alice",
|
||||
"message": "thisgame++",
|
||||
"timestamp": "2025-10-30T20:15:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
3. Import this JSON file into the Jackbox Game Picker app
|
||||
|
||||
### Resetting Votes
|
||||
|
||||
- Click "Reset Votes" to clear all recorded votes
|
||||
- Confirmation dialog prevents accidental resets
|
||||
|
||||
## How It Works
|
||||
|
||||
The extension hooks into Kosmi's GraphQL WebSocket API (`wss://engine.kosmi.io/gql-ws`) to monitor real-time chat messages. This is much more reliable than DOM parsing!
|
||||
|
||||
When a message is received, the extension:
|
||||
1. Checks if it contains `thisgame++` or `thisgame--` (case-insensitive)
|
||||
2. Extracts the **username** from the GraphQL response
|
||||
3. Extracts the **full message text**
|
||||
4. Records the **UTC timestamp**
|
||||
|
||||
### Why WebSocket?
|
||||
|
||||
Previous versions used DOM parsing (MutationObserver), which was fragile and prone to breaking when Kosmi updated their UI. Version 3.0.0 uses Kosmi's own GraphQL API, which is:
|
||||
- ✅ More reliable (API is stable)
|
||||
- ✅ Faster (no DOM traversal needed)
|
||||
- ✅ More accurate (username is always correct)
|
||||
- ✅ Less CPU intensive (no constant DOM monitoring)
|
||||
|
||||
## Vote Format
|
||||
|
||||
**Input** (Kosmi chat):
|
||||
```
|
||||
Alice: This is great! thisgame++
|
||||
Bob: thisgame-- not my favorite
|
||||
Charlie: THISGAME++ love it!
|
||||
```
|
||||
|
||||
**Output** (JSON export):
|
||||
```json
|
||||
[
|
||||
{
|
||||
"username": "Alice",
|
||||
"message": "This is great! thisgame++",
|
||||
"timestamp": "2025-10-30T20:15:00.123Z"
|
||||
},
|
||||
{
|
||||
"username": "Bob",
|
||||
"message": "thisgame-- not my favorite",
|
||||
"timestamp": "2025-10-30T20:15:15.456Z"
|
||||
},
|
||||
{
|
||||
"username": "Charlie",
|
||||
"message": "THISGAME++ love it!",
|
||||
"timestamp": "2025-10-30T20:15:30.789Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### Files
|
||||
|
||||
- `manifest.json`: Extension configuration
|
||||
- `content.js`: Monitors Kosmi chat and records votes
|
||||
- `popup.html`: Extension popup interface
|
||||
- `popup.js`: Popup logic and controls
|
||||
- `popup.css`: Popup styling
|
||||
- `icons/`: Extension icons
|
||||
|
||||
### Permissions
|
||||
|
||||
- `storage`: Save votes locally
|
||||
- `activeTab`: Access current Kosmi tab
|
||||
- `downloads`: Export JSON files
|
||||
- `https://app.kosmi.io/*`: Access Kosmi chat
|
||||
|
||||
### Data Storage
|
||||
|
||||
- Votes are stored locally using Chrome's `storage.local` API
|
||||
- Data persists across browser sessions
|
||||
- No data is sent to external servers
|
||||
|
||||
## Changelog
|
||||
|
||||
### Version 3.0.1 (Current)
|
||||
|
||||
- 🐛 Fixed infinite retry loop when Apollo Client not found
|
||||
- 🐛 Disabled auto-start on page load (user must manually start tracking)
|
||||
- ✅ Added retry limit (10 attempts max, then gives up gracefully)
|
||||
- ✅ Only sets `isTracking = true` after successfully hooking into Apollo Client
|
||||
- ✅ Better error messages with attempt counter
|
||||
|
||||
### Version 3.0.0
|
||||
|
||||
- 🎉 **Complete rewrite using GraphQL WebSocket API**
|
||||
- ✅ Hooks directly into Kosmi's Apollo Client
|
||||
- ✅ 100% reliable message and username extraction
|
||||
- ✅ No more DOM parsing or MutationObserver
|
||||
- ✅ Lightweight and performant
|
||||
- ✅ Future-proof (API-based, not DOM-based)
|
||||
- ❌ Removed fragile DOM traversal code
|
||||
- ❌ No more "Unknown" usernames
|
||||
|
||||
### Version 2.0.2
|
||||
|
||||
- 🐛 Fixed sidebar responsiveness with polling updates
|
||||
- 🐛 Fixed MutationObserver not detecting new messages
|
||||
- 🐛 Suppressed "Could not establish connection" errors
|
||||
- ✅ Added extensive debug logging for troubleshooting
|
||||
- ✅ Observer now properly disconnects and reconnects on start
|
||||
|
||||
### Version 2.0.1
|
||||
|
||||
- 🐛 Fixed duplicate vote counting issue
|
||||
- 🐛 Improved username extraction with multiple fallback strategies
|
||||
- ✅ Re-added sidebar panel support
|
||||
|
||||
### Version 2.0.0
|
||||
|
||||
- ✅ Simplified to only track `thisgame++` and `thisgame--`
|
||||
- ✅ Removed complex game alias system
|
||||
- ✅ Captures full message context
|
||||
- ✅ UTC timestamp recording
|
||||
- ✅ New JSON export format
|
||||
- ✅ Improved UI with vote preview
|
||||
- ✅ Case-insensitive matching
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Extension not detecting votes:**
|
||||
1. Make sure you're on a Kosmi room page (`app.kosmi.io/room/...`)
|
||||
2. Click "Stop Tracking" then "Start Tracking" to reset
|
||||
3. Check browser console for errors (F12 → Console tab)
|
||||
|
||||
**Votes not saving:**
|
||||
1. Check Chrome's storage permissions
|
||||
2. Try resetting votes and starting fresh
|
||||
3. Ensure extension has permission to access Kosmi
|
||||
|
||||
**Export not working:**
|
||||
1. Check Chrome's download permissions
|
||||
2. Ensure popup blockers aren't blocking downloads
|
||||
3. Try clicking "Export JSON" again
|
||||
|
||||
**Extension not loading:**
|
||||
1. Make sure you've reloaded the extension after updating files
|
||||
2. Go to `chrome://extensions/`, find "Jackbox Chat Tracker", and click the reload icon
|
||||
3. Refresh the Kosmi room page after reloading the extension
|
||||
|
||||
**Apollo Client not found:**
|
||||
1. The extension needs a moment after page load to find Apollo Client
|
||||
2. Wait 2-3 seconds after the page loads, then click "Start Tracking"
|
||||
3. Check console for "Apollo Client not found!" error
|
||||
4. If error persists, Kosmi may have changed their client framework
|
||||
|
||||
## Support
|
||||
|
||||
For issues or questions, please file an issue in the main repository.
|
||||
|
||||
## License
|
||||
|
||||
Same as main Jackbox Game Picker project.
|
||||
|
||||
Reference in New Issue
Block a user