The 3D Globe shows your visitors in real-time. Understand how the live updates work and how the globe handles different traffic levels.
How Real-Time Works
Supabase Real-Time Subscription
The Globe uses Supabase real-time subscriptions to receive instant visitor updates:
- Subscribes to the
visitorstable filtered by your website ID - Listens for
INSERTevents (new visitor page loads) - Updates are pushed instantly without page refresh
- Connection is managed automatically
Update Flow
When someone visits your site:
- Tracking script fires - Visitor data is sent to the Zenovay API
- Data stored - Visitor record is inserted into the database
- Real-time broadcast - Supabase pushes the new record to the globe
- Marker appears - A DiceBear avatar marker appears at the visitor's location
This process typically takes 1-2 seconds from page load to marker appearance.
Fallback Polling
In addition to real-time subscriptions, the globe has a 30-second polling interval as a safety net:
- Polls the
/api/globe/visitorsendpoint every 30 seconds - Only runs when the browser tab is visible (checks
document.hidden) - Catches any updates that may have been missed by the real-time subscription
- Ensures data stays fresh even if the subscription temporarily disconnects
Visitor Data Lifecycle
2-Minute Rolling Window
The globe shows visitors from the last 2 minutes:
| Event | Timing |
|---|---|
| Visitor loads a page | Marker appears immediately |
| 2 minutes pass | Marker is removed |
| Same session, new page | Old marker replaced with new one |
Marker Limit
Up to 50 visitor markers are displayed simultaneously:
- The most recent visitors are prioritized
- When a new visitor arrives and the limit is reached, the oldest marker is removed
- The stats overlay always shows the accurate count regardless of the marker limit
Deduplication
If a visitor with an existing session loads another page:
- The previous marker for that session is replaced
- Only the most recent page view for each session is shown
- This prevents duplicate markers for the same visitor
Disconnection Handling
Why Disconnections Happen
Common causes:
- Network interruption
- Browser tab backgrounded for extended periods
- VPN or firewall issues
- Browser sleep mode
What Happens When Disconnected
During disconnection:
- The globe shows the last known visitor data
- Markers from the 2-minute window may expire and disappear
- The fallback polling will stop if the tab is hidden
Reconnection
When the connection is restored or the tab is foregrounded:
- The Supabase real-time subscription reconnects automatically
- The fallback polling resumes and fetches fresh data
- Markers update to reflect the current state
Manual Refresh
If data seems stale:
- Click the Reload button in the globe control bar
- This triggers an immediate data fetch
- Fresh visitor data replaces the current markers
Tab Behavior
Active Tab
When the globe tab is in the foreground:
- Real-time subscription delivers updates instantly
- 30-second fallback polling runs as a safety net
- Full rendering and animations active
Backgrounded Tab
When the globe tab is not the active tab:
- The browser may throttle the connection
- Fallback polling pauses (detects
document.hidden) - Rendering pauses to conserve resources
Returning to Tab
When you switch back to the globe tab:
- Fallback polling resumes immediately
- A fresh data fetch is triggered
- Markers update to reflect current visitors
- The real-time subscription catches up on any queued events
High Traffic Handling
Marker Cap
The globe limits visible markers to 50, regardless of traffic volume:
- This ensures consistent performance even during traffic spikes
- New visitors are always shown (oldest markers are removed first)
- The Top Stats overlay shows accurate aggregate counts
Visitor Expiration
Visitors older than 2 minutes are automatically expired:
- This keeps the globe focused on current activity
- Prevents marker buildup during sustained high traffic
- Expired visitors are filtered out during both real-time and polling updates
Performance Tips
For Real-Time Reliability
| Tip | Reason |
|---|---|
| Keep the tab in the foreground | Prevents browser throttling |
| Use a stable internet connection | Reduces disconnections |
| Close unnecessary tabs | Frees browser resources |
| Enable hardware acceleration | Improves rendering performance |
For Office Displays
If using the globe as a live display:
- Keep the browser tab active and in the foreground
- Use fullscreen mode for visual impact
- Enable the music player for ambient audio
- The 30-second fallback ensures data stays fresh even if the real-time subscription briefly drops
For Presentations
- Test the globe connection before presenting
- Have a stable network connection
- Use fullscreen mode
- Click Reload if markers are not appearing as expected
Troubleshooting
No Real-Time Updates
If the Globe is not updating:
- Click the Reload button to trigger a manual refresh
- Check your internet connection
- Verify the tracking script is installed and working on your website
- Open the browser developer console (F12) and look for errors
- Try refreshing the page
Delayed Updates
If updates seem slow:
- Check your network latency
- Disable VPN if active (may add latency)
- Close bandwidth-heavy applications
- Ensure the tab is in the foreground
Markers Not Appearing
If visitors are not showing:
- Verify the tracking script is installed on your website
- Confirm visitors exist in your analytics dashboard
- Ensure the correct website is selected
- Check that you have active traffic (markers expire after 2 minutes)