How GoSquared Works
GoSquared is a real-time web analytics and customer engagement platform that unifies traffic analytics, people profiles, and live chat in a single JavaScript SDK. Unlike batch-processing analytics tools that show yesterday's numbers, GoSquared updates its Now dashboard within seconds of a visitor action.
The data model has three layers. The traffic layer records pageviews, sessions, referrers, and geographic data in real time. The people layer builds individual profiles that accumulate page history, custom properties, and transaction records across sessions. The engagement layer provides live chat and triggered messages based on visitor behavior.
When the GoSquared snippet loads, it establishes a persistent WebSocket connection to GoSquared's servers. This is how the Now dashboard can show you exactly who is on your site at any given moment, what page they are viewing, and how long they have been active. Every pageview, identify call, and event flows through this connection with sub-second latency.
GoSquared assigns each anonymous visitor a cookie-based ID. When you call identify with a known user ID, all anonymous history merges into the named profile. The people database retains this merged history indefinitely, allowing you to see the full journey from first anonymous visit through signup, purchase, and ongoing engagement.
Installing the GoSquared Script
Add the following snippet before the closing </head> tag. Replace GSN-XXXXXX-X with your GoSquared site token from the Settings page.
<script>
!function(g,s,q,r,d){r=g[r]=g[r]||function(){(r.q=r.q||[]).push(arguments)};
d=s.createElement(q);d.src='//d1l6p2sc9645hc.cloudfront.net/gosquared.js';
q=s.getElementsByTagName(q)[0];q.parentNode.insertBefore(d,q)}
(window,document,'script','_gs');
_gs('GSN-XXXXXX-X');
_gs('set', 'anonymizeIP', true); // Optional: anonymize visitor IPs
</script>
For Google Tag Manager, create a Custom HTML tag with this snippet. Set the firing trigger to All Pages and configure the tag to fire before any tags that depend on the _gs function.
<!-- GTM Custom HTML Tag -->
<script>
!function(g,s,q,r,d){r=g[r]=g[r]||function(){(r.q=r.q||[]).push(arguments)};
d=s.createElement(q);d.src='//d1l6p2sc9645hc.cloudfront.net/gosquared.js';
q=s.getElementsByTagName(q)[0];q.parentNode.insertBefore(d,q)}
(window,document,'script','_gs');
_gs('GSN-XXXXXX-X');
</script>
Verify the installation by opening your site in a browser, then checking the GoSquared Now dashboard. Your visit should appear within 2-3 seconds. You can also type _gs in the browser console to confirm the function is defined.
Core Tracking Features
Automatic Pageview Tracking
GoSquared tracks pageviews automatically on initial page load. For single-page applications where the URL changes without a full reload, manually trigger a pageview on each route transition:
// Call after each client-side navigation
_gs('track');
In a React application with React Router:
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
function useGoSquaredPageTracking() {
const location = useLocation();
useEffect(() => {
if (typeof _gs === 'function') {
_gs('track');
}
}, [location.pathname]);
}
Identifying Users (People Analytics)
Call identify when you know who the visitor is. Pass the user's unique ID and an object of profile properties.
_gs('identify', {
id: 'user-12345',
name: 'Jane Martinez',
email: 'jane@example.com',
company: {
name: 'Acme Corp',
size: 50,
industry: 'SaaS'
},
custom: {
plan: 'Business',
signup_date: '2025-11-15',
mrr: 199
}
});
The id field is the permanent identifier that links sessions across devices. The name and email fields populate the People dashboard. Everything under custom appears as filterable properties on the person's profile.
You can update properties at any time by calling identify again with the same id. New properties are added, and existing properties are overwritten with the new values.
Unidentifying Users (Logout)
When a user logs out, call unidentify so subsequent pageviews are not attributed to the previous user:
_gs('unidentify');
Custom Event Tracking
GoSquared supports custom event tracking through the event method. Events appear in the person's activity timeline and can be used for segmentation.
// Simple event
_gs('event', 'Clicked Upgrade Button');
// Event with properties
_gs('event', 'Completed Onboarding', {
steps_completed: 5,
time_to_complete: '3m 42s',
skipped_steps: ['invite_team']
});
// E-commerce events
_gs('event', 'Added to Cart', {
product: 'Annual Pro Plan',
price: 499,
currency: 'USD'
});
Tracking Transactions
GoSquared has a dedicated transaction API for revenue tracking. Transactions link to the identified person and feed into revenue dashboards.
_gs('transaction', {
id: 'txn-98765',
revenue: 499.00,
quantity: 1,
items: [
{
name: 'Pro Plan - Annual',
price: 499.00,
quantity: 1,
category: 'Subscription'
}
]
});
Each transaction requires a unique id to prevent double-counting. If you send the same transaction ID twice, GoSquared ignores the duplicate.
The Now Dashboard
The Now dashboard is GoSquared's signature feature. It shows a real-time feed of every visitor currently on your site, including:
- Current page URL and page title
- Geographic location (city-level)
- Referral source or UTM campaign
- Device type and browser
- Time on site and pages viewed in this session
- Whether the visitor is identified (with name and email)
You can click any visitor to see their full profile history. For identified users, this includes every pageview, event, and transaction across all sessions. The Now dashboard also supports filtering, so you can watch only visitors from a specific campaign or geographic region.
Integration with Other Tools
Forwarding Events to GA4 via dataLayer
Push GoSquared events into the GTM dataLayer to create corresponding GA4 events without duplicating tracking code:
function trackWithGoSquaredAndGA4(eventName, properties) {
// Track in GoSquared
_gs('event', eventName, properties);
// Forward to GA4 via GTM dataLayer
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: 'gs_' + eventName.toLowerCase().replace(/\s+/g, '_'),
...properties
});
}
trackWithGoSquaredAndGA4('Purchased Plan', {
plan: 'Business',
revenue: 199,
billing: 'monthly'
});
GoSquared REST API
GoSquared exposes a REST API for server-side operations. Use it to identify users from your backend, track events from webhooks, or export data.
# Identify a user server-side
curl -X POST "https://api.gosquared.com/people/v1/identify" \
-H "Content-Type: application/json" \
-d '{
"site_token": "GSN-XXXXXX-X",
"api_key": "YOUR_API_KEY",
"person_id": "user-12345",
"properties": {
"name": "Jane Martinez",
"email": "jane@example.com",
"custom": {
"plan": "Enterprise",
"seats": 25
}
}
}'
# Track a server-side event
curl -X POST "https://api.gosquared.com/tracking/v1/event" \
-H "Content-Type: application/json" \
-d '{
"site_token": "GSN-XXXXXX-X",
"api_key": "YOUR_API_KEY",
"person_id": "user-12345",
"event": "Subscription Renewed",
"properties": {
"revenue": 199,
"plan": "Business"
}
}'
Webhook and CRM Integration
GoSquared can send webhook notifications when visitors perform specific actions or match segment criteria. Configure webhooks in Settings to push data to Slack, Zapier, or your own endpoints for CRM synchronization.
Common Errors
| Error | Cause | Fix |
|---|---|---|
| Visitor count is zero on Now dashboard | Script blocked by ad blocker or CSP header | Add d1l6p2sc9645hc.cloudfront.net to your Content-Security-Policy script-src directive |
_gs is not a function |
GoSquared snippet did not load or loaded after dependent code | Place the GoSquared snippet in <head> before any code that calls _gs() |
| Pageviews not tracking on SPA | GoSquared only auto-tracks the initial page load | Call _gs('track') on every client-side route change |
| People profiles show as anonymous | identify never called, or called without an id field |
Always pass an id property inside the identify object |
| Duplicate people profiles | Different id values used for the same person across contexts |
Use one consistent identifier (e.g., database user ID) everywhere |
| Transaction revenue not appearing | Missing id on the transaction or duplicate transaction ID |
Every transaction needs a unique id string; check for duplicates |
| Events not appearing on person timeline | Event tracked before identify was called on that device |
Call identify before tracking events, or accept that pre-identify events attach to anonymous profiles |
| Chat widget not showing | Chat module disabled in GoSquared settings, or script load failure | Enable the chat module in your GoSquared site settings and verify the script loads |
| High bounce rate despite engagement | GoSquared counts a bounce as a single-pageview session | Use _gs('event', ...) to register engagement signals that indicate a non-bounce |
| Real-time data delayed by minutes | WebSocket connection blocked by corporate proxy or firewall | Verify that WebSocket connections to *.gosquared.com are allowed |
Performance Considerations
The GoSquared JavaScript library is approximately 30 KB gzipped. It loads asynchronously and uses a WebSocket connection for real-time data transmission. The WebSocket connection adds a small amount of ongoing bandwidth (a few bytes per event) but has negligible impact on page performance.
Because GoSquared maintains a persistent connection, it consumes slightly more resources than fire-and-forget analytics scripts. On pages where visitors stay for extended periods (dashboards, documentation), this is a non-issue. On landing pages where visitors leave quickly, the connection overhead is irrelevant because it closes with the page.
For sites with strict performance budgets, you can defer GoSquared loading until after the critical rendering path:
// Load GoSquared after page is interactive
window.addEventListener('load', function () {
!function(g,s,q,r,d){r=g[r]=g[r]||function(){(r.q=r.q||[]).push(arguments)};
d=s.createElement(q);d.src='//d1l6p2sc9645hc.cloudfront.net/gosquared.js';
q=s.getElementsByTagName(q)[0];q.parentNode.insertBefore(d,q)}
(window,document,'script','_gs');
_gs('GSN-XXXXXX-X');
});
This delays initial pageview tracking by the time it takes the load event to fire, but preserves LCP and First Input Delay (FID) scores.