GoSquared Tracking Approaches

Tracking Approaches Overview

GoSquared supports both client-side (browser-based) and server-side tracking, each with distinct advantages. Understanding when to use each approach ensures accurate data collection, better security, and optimal performance.

Client-Side Tracking

Client-side tracking uses JavaScript executed in the user's browser to collect data in real-time.

When to Use Client-Side

Best for:

Web Analytics: Page views, sessions, and visitor behavior
Real-time Dashboard: Live visitor monitoring in GoSquared Now
User Interactions: Clicks, scrolls, form interactions
Live Chat: Customer engagement features
Anonymous Visitors: Tracking before user identification
Client-Side Events: DOM interactions, JavaScript errors

Implementation

Basic client-side tracking:

<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-123456-A');
</script>

Client-Side Event Tracking

// Track user interactions
_gs('event', 'Button Clicked', {
  button_name: 'Sign Up',
  page_location: window.location.pathname
});

// Identify users
_gs('identify', {
  id: 'user_123',
  email: 'user@example.com',
  name: 'John Doe'
});

// Update user properties
_gs('properties', {
  last_page_viewed: window.location.href,
  session_start: new Date().toISOString()
});

Advantages of Client-Side

Automatic Page Tracking: Page views tracked automatically
Real-Time Visibility: Immediate appearance in GoSquared Now dashboard
Browser Context: Access to DOM, cookies, user agent, screen size
Easy Implementation: Simple script tag integration
Live Chat Integration: Enable customer support features
Session Tracking: Automatic session management

Limitations of Client-Side

Ad Blockers: Privacy extensions may block tracking
Network Required: Won't work offline
Client Performance: Can impact page load time
Security: API tokens visible in page source
Limited to Browser: Can't track server-side actions
Data Integrity: Users can manipulate or block requests

Server-Side Tracking

Server-side tracking sends data from your backend servers directly to GoSquared's API.

When to Use Server-Side

Best for:

Backend Events: Actions that occur on your servers
Secure Transactions: Payment processing, subscriptions
API Integrations: Webhook handlers, background jobs
Sensitive Data: Events requiring server validation
Guaranteed Delivery: Critical events that can't be blocked
Mobile Apps: iOS and Android backend tracking
Batch Processing: Importing historical data

Implementation

Node.js

Install the GoSquared SDK:

npm install gosquared

Basic setup:

const GoSquared = require('gosquared');
const gs = new GoSquared({
  site_token: 'GSN-123456-A',
  api_key: 'your_api_key'  // Required for server-side
});

// Track event
gs.trackEvent({
  person_id: 'user_123',
  event: 'Subscription Renewed',
  properties: {
    plan: 'professional',
    amount: 49.99,
    billing_cycle: 'monthly'
  }
});

// Identify user
gs.identify({
  id: 'user_123',
  properties: {
    email: 'user@example.com',
    name: 'John Doe',
    plan: 'professional'
  }
});

Python

from gosquared import Tracker

tracker = Tracker(
    site_token='GSN-123456-A',
    api_key='your_api_key'
)

# Track event
tracker.track_event(
    person_id='user_123',
    event='Subscription Renewed',
    properties={
        'plan': 'professional',
        'amount': 49.99,
        'billing_cycle': 'monthly'
    }
)

# Identify user
tracker.identify(
    person_id='user_123',
    properties={
        'email': 'user@example.com',
        'name': 'John Doe',
        'plan': 'professional'
    }
)

Ruby

require 'gosquared'

GoSquared.configure do |config|
  config.site_token = 'GSN-123456-A'
  config.api_key = 'your_api_key'
end

# Track event
GoSquared.track_event(
  person_id: 'user_123',
  event: 'Subscription Renewed',
  properties: {
    plan: 'professional',
    amount: 49.99,
    billing_cycle: 'monthly'
  }
)

PHP

<?php
require 'vendor/autoload.php';

use GoSquared\GoSquared;

$gs = new GoSquared([
    'site_token' => 'GSN-123456-A',
    'api_key' => 'your_api_key'
]);

// Track event
$gs->trackEvent([
    'person_id' => 'user_123',
    'event' => 'Subscription Renewed',
    'properties' => [
        'plan' => 'professional',
        'amount' => 49.99,
        'billing_cycle' => 'monthly'
    ]
]);

Server-Side Use Cases

Track Subscription Events

// Stripe webhook handler
app.post('/webhooks/stripe', async (req, res) => {
  const event = req.body;

  if (event.type === 'customer.subscription.created') {
    gs.trackEvent({
      person_id: event.data.object.customer,
      event: 'Subscription Created',
      properties: {
        plan: event.data.object.items.data[0].price.id,
        amount: event.data.object.items.data[0].price.unit_amount / 100,
        currency: event.data.object.currency
      }
    });
  }

  res.sendStatus(200);
});

Track Backend Processes

// Background job
async function processUserData(userId) {
  try {
    await processData(userId);

    gs.trackEvent({
      person_id: userId,
      event: 'Data Processing Completed',
      properties: {
        processing_time_ms: Date.now() - startTime,
        records_processed: recordCount
      }
    });
  } catch (error) {
    gs.trackEvent({
      person_id: userId,
      event: 'Data Processing Failed',
      properties: {
        error_message: error.message
      }
    });
  }
}

Track API Usage

// API middleware
app.use((req, res, next) => {
  res.on('finish', () => {
    if (req.user) {
      gs.trackEvent({
        person_id: req.user.id,
        event: 'API Request',
        properties: {
          endpoint: req.path,
          method: req.method,
          status_code: res.statusCode,
          response_time_ms: Date.now() - req.startTime
        }
      });
    }
  });
  next();
});

Advantages of Server-Side

Guaranteed Delivery: No ad blockers or client-side interference
Secure: API keys not exposed to browsers
Reliable: Not dependent on client behavior
Backend Events: Track server-only actions
Batch Operations: Efficient bulk data import
Validation: Verify data before sending

Limitations of Server-Side

No Automatic Page Views: Must manually track navigation
No Browser Context: Can't access DOM, cookies, etc.
Not Real-Time Dashboard: May not appear in Now view immediately
Requires Backend: Need server infrastructure
No Live Chat: Chat features require client-side script

Hybrid Approach (Recommended)

Combine both approaches for comprehensive tracking:

Implementation Strategy

Client-Side For:

Page views and navigation
User interface interactions
Real-time visitor monitoring
Live chat support
Anonymous visitor tracking

Server-Side For:

Payment transactions
Subscription changes
Account updates
Background processes
Webhook events

Example: Complete Implementation

// Client-side (frontend)
<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-123456-A');

  // Track client-side events
  document.getElementById('signup-btn').addEventListener('click', () => {
    _gs('event', 'Signup Button Clicked');
  });
</script>

// Server-side (backend)
const gs = new GoSquared({ site_token: 'GSN-123456-A', api_key: 'API_KEY' });

app.post('/api/signup', async (req, res) => {
  const user = await createUser(req.body);

  // Track server-side event
  gs.trackEvent({
    person_id: user.id,
    event: 'Account Created',
    properties: {
      plan: user.plan,
      signup_method: req.body.method
    }
  });

  res.json({ success: true });
});

Comparison Table

Feature	Client-Side	Server-Side
Page view tracking	Automatic	Manual
Real-time dashboard	Yes	Limited
Ad blocker resistance	No	Yes
Backend events	No	Yes
Live chat	Yes	No
Security	Lower (exposed tokens)	Higher (server keys)
Reliability	Depends on client	Guaranteed
Implementation	Simple script tag	SDK integration
Browser context	Full access	None
Offline capability	No	Yes (queue)

Best Practices

Use Client-Side for UI: Track all user interface interactions
Use Server-Side for Transactions: Critical events like payments
Consistent User IDs: Use same ID in both client and server
Secure API Keys: Never expose server API keys in client code
Validate Server-Side: Validate data before sending
Handle Errors: Implement error handling for both approaches
Test Both Channels: Verify events from client and server appear correctly
Monitor Performance: Track impact on both client and server performance
Document Events: Maintain clear documentation of what's tracked where
Consider Privacy: Respect user privacy in both implementations

Troubleshooting

Issue	Approach	Solution
Events not appearing	Client-side	Check for ad blockers, console errors
Duplicate events	Hybrid	Ensure same event not tracked both ways
Missing page views	Server-side	Manually track page views or add client-side
API authentication error	Server-side	Verify API key is correct
Real-time not working	Server-side	Use client-side for real-time features
Performance impact	Client-side	Use async loading, minimize events

Decision Guide

Choose Client-Side When:

You need real-time visitor dashboard
Tracking web page interactions
Using live chat features
Quick implementation needed
Tracking anonymous visitors

Choose Server-Side When:

Processing payments or subscriptions
Handling webhook events
Running background jobs
Data accuracy is critical
Ad blockers are a concern

Choose Hybrid When:

Building production applications
Need comprehensive tracking
Both web and backend events matter
Security and reliability are important