jackboxpartypack-gamepicker/chrome-extension/DEBUG.md

Chrome Extension Debugging Guide

Version 3.0.2 - Apollo Client Detection Issues

If the extension can't find Apollo Client, follow these steps to diagnose the issue:

Step 1: Reload Extension and Page

1. Go to chrome://extensions/
2. Find "Jackbox Chat Tracker for Kosmi"
3. Click the reload icon (circular arrow)
4. Navigate to Kosmi room: https://app.kosmi.io/room/@yourroomname
5. Refresh the page (Ctrl+R or Cmd+R)

Step 2: Run Debug Function

1. Open Chrome DevTools (F12)
2. Go to Console tab
3. Wait 5-10 seconds after page load (let Kosmi fully initialize)
4. Type: window.debugJackboxTracker()
5. Press Enter

Step 3: Analyze Output

The debug function will show:

If Apollo Client is Found ✓

=== Jackbox Chat Tracker Debug ===
✓ Apollo Client found!
Apollo Client: ApolloClient {...}
Apollo Client keys: ['cache', 'link', 'queryManager', ...]
Apollo Link: {...}
Apollo Link keys: ['client', ...]
GraphQL client: {...}
GraphQL client keys: ['on', 'subscribe', 'iterate', 'dispose', 'terminate']
=== End Debug ===

Action: Try clicking "Start Tracking" in the extension popup. It should work now!

If Apollo Client is NOT Found ✗

=== Jackbox Chat Tracker Debug ===
✗ Apollo Client not found
Checking for window.__APOLLO_CLIENT__: undefined
Window keys that might be relevant: ['__someOtherKey__', ...]
=== End Debug ===

Action: Copy the "Window keys that might be relevant" list and report it to the developer.

Step 4: Check Timing

If Apollo Client is not found immediately, wait longer and try again:

// Run debug after 10 seconds
setTimeout(() => window.debugJackboxTracker(), 10000);

Step 5: Manual Apollo Client Search

If still not working, manually check for Apollo Client:

// Check if it exists
console.log('window.__APOLLO_CLIENT__:', window.__APOLLO_CLIENT__);

// Search all window properties
Object.keys(window).forEach(key => {
  if (key.includes('apollo') || key.includes('Apollo')) {
    console.log('Found Apollo-related key:', key, window[key]);
  }
});

// Check if it's in a different location
console.log('document.__APOLLO_CLIENT__:', document.__APOLLO_CLIENT__);

Common Issues

Issue: "Apollo Client not found after 15 attempts"

Causes:

1. Kosmi changed their client variable name
2. Apollo Client loads after 15 seconds
3. You're not on a Kosmi room page

Solutions:

1. Wait longer (30+ seconds) and run window.debugJackboxTracker()
2. Make sure you're on app.kosmi.io/room/... not just app.kosmi.io
3. Try a different room
4. Check if Kosmi updated their code

Issue: "GraphQL client not found in Apollo Client"

Cause: Apollo Client structure changed

Solution:

1. Run debug function to see Apollo Client structure
2. Look for the WebSocket client in a different location
3. Report the structure to the developer

Reporting Issues

When reporting Apollo Client not found, include:

1. Console Output:

   // Copy ALL of this:
   window.debugJackboxTracker()
   

2. Window Keys:

   // Copy this:
   Object.keys(window).filter(k => k.startsWith('__') || k.includes('apollo'))
   

3. Kosmi URL:

   • Full URL of the room (redact room name if private)

4. Browser Version:

   • Chrome version (chrome://version/)

5. Extension Version:

   • Check chrome://extensions/ → "Jackbox Chat Tracker" → version number

---

Advanced Debugging

Hook Detection

Check if the WebSocket hook is working:

// This should exist after successfully starting tracking
console.log('GraphQL Client:', window.__APOLLO_CLIENT__?.link?.client);

// Try manually hooking
const client = window.__APOLLO_CLIENT__.link.client;
client.on('message', (data) => {
  console.log('MANUAL HOOK - Message:', data);
});

Message Interception

Test if messages are flowing:

// Send a test message in Kosmi chat: "test thisgame++"
// Check console for:
// [Jackbox Chat Tracker] New message: {...}
// [Jackbox Chat Tracker] ✓ Vote detected!

---

Version History

v3.0.2

• Added multiple Apollo Client detection strategies
• Added window.debugJackboxTracker() debug function
• Extended search to all window/document properties
• Increased retry limit to 15 attempts (15-30 seconds)
• Added detailed error logging

v3.0.1

• Fixed infinite loop on page load
• Disabled auto-start tracking
• Added retry limit

v3.0.0

• Initial WebSocket API implementation
• Replaced DOM parsing with GraphQL subscriptions