GoSquared Data Layer Setup | Blue Frog Docs

GoSquared Data Layer Setup

Configure user properties and custom data in GoSquared.

Data Layer Overview

GoSquared's data layer allows you to enrich visitor profiles with custom properties, user attributes, and behavioral data. This enables powerful segmentation, personalized engagement, and detailed analytics based on your specific business data.

 

 

User Identification

User identification is the foundation of GoSquared's data layer. It links anonymous sessions to known users and enriches profiles with identifying information.

Basic Identification

Identify users with their unique ID and basic attributes:

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

Complete Identification

Include all available user attributes:

_gs('identify', {
  id: 'user_abc123',
  email: 'john.doe@example.com',
  name: 'John Doe',
  first_name: 'John',
  last_name: 'Doe',
  phone: '+1-555-0123',
  created_at: '2024-01-15T10:30:00Z',
  username: 'johndoe'
});

When to Identify

Call identify at these key moments:

  1. After successful login
  2. After user registration
  3. On page load (if user is authenticated)
  4. After profile updates
// After login
function handleLoginSuccess(user) {
  _gs('identify', {
    id: user.id,
    email: user.email,
    name: user.full_name
  });
}

// On page load for authenticated users
if (currentUser) {
  _gs('identify', {
    id: currentUser.id,
    email: currentUser.email,
    name: currentUser.name
  });
}

 

 

Custom Properties

Custom properties allow you to store business-specific data about users.

Standard Custom Properties

_gs('identify', {
  id: 'user_123',
  custom: {
    plan: 'enterprise',
    company: 'Acme Inc',
    industry: 'Technology',
    mrr: 499,
    employee_count: 50,
    signup_source: 'google_ads'
  }
});

Property Data Types

GoSquared supports multiple data types:

_gs('identify', {
  id: 'user_123',
  custom: {
    // String
    plan_name: 'Professional',

    // Number
    total_spend: 1299.99,

    // Boolean
    is_trial: false,
    email_verified: true,

    // Date (ISO 8601 format)
    trial_ends_at: '2024-12-31T23:59:59Z',

    // Array
    tags: ['vip', 'power-user', 'beta-tester'],

    // Object
    preferences: {
      theme: 'dark',
      notifications: true
    }
  }
});

E-commerce Properties

For e-commerce tracking:

_gs('identify', {
  id: 'customer_456',
  email: 'customer@example.com',
  custom: {
    lifetime_value: 2499.99,
    total_orders: 12,
    average_order_value: 208.33,
    last_purchase_date: '2024-03-15',
    favorite_category: 'Electronics',
    customer_segment: 'High Value',
    loyalty_tier: 'Gold'
  }
});

B2B/SaaS Properties

For B2B or SaaS applications:

_gs('identify', {
  id: 'user_789',
  email: 'admin@company.com',
  custom: {
    company_id: 'comp_123',
    company_name: 'Acme Corporation',
    account_type: 'enterprise',
    mrr: 999,
    arr: 11988,
    seats: 25,
    contract_end_date: '2025-12-31',
    account_manager: 'Sarah Johnson',
    onboarding_completed: true,
    features_enabled: ['sso', 'api', 'premium-support']
  }
});

 

 

Update Properties

Update user properties without re-identifying the user:

Update Specific Properties

_gs('properties', {
  last_login: new Date().toISOString(),
  login_count: 42,
  last_page_viewed: window.location.pathname
});

Increment Numeric Properties

// Track usage metrics
_gs('properties', {
  sessions_count: existingCount + 1,
  total_events: currentTotal + 1
});

Update After User Actions

// After completing onboarding
function completeOnboarding() {
  _gs('properties', {
    onboarding_completed: true,
    onboarding_completed_at: new Date().toISOString(),
    onboarding_steps_completed: 5
  });
}

// After subscription upgrade
function handleSubscriptionUpgrade(newPlan) {
  _gs('properties', {
    plan: newPlan.name,
    mrr: newPlan.price,
    upgraded_at: new Date().toISOString(),
    previous_plan: currentPlan.name
  });
}

 

 

Standard vs Custom Properties

Standard Properties

These are recognized by GoSquared and appear in dedicated UI sections:

  • id - Unique user identifier
  • email - User email address
  • name - Full name
  • first_name - First name
  • last_name - Last name
  • phone - Phone number
  • created_at - Account creation date
  • username - Username

Custom Properties

All other properties go in the custom object:

_gs('identify', {
  // Standard properties
  id: 'user_123',
  email: 'user@example.com',
  name: 'John Doe',

  // Custom properties
  custom: {
    subscription_tier: 'pro',
    department: 'Engineering',
    role: 'Developer'
  }
});

 

 

Property Naming Conventions

Follow these conventions for consistency:

_gs('identify', {
  id: 'user_123',
  custom: {
    // Use snake_case
    subscription_tier: 'enterprise',
    account_created_at: '2024-01-01',

    // Be descriptive
    total_revenue_usd: 5000,
    last_login_timestamp: '2024-03-20T10:30:00Z',

    // Use boolean prefixes
    is_premium: true,
    has_completed_tutorial: false,

    // Use consistent units
    contract_value_usd: 12000,
    trial_duration_days: 14
  }
});

 

 

Common Use Cases

Track User Lifecycle Stage

function updateUserStage(stage) {
  _gs('properties', {
    lifecycle_stage: stage,
    stage_entered_at: new Date().toISOString()
  });
}

// Call when stage changes
updateUserStage('trial');
updateUserStage('active');
updateUserStage('churned');

Track Feature Adoption

function trackFeatureUsage(featureName) {
  _gs('properties', {
    [`feature_${featureName}_first_used`]: new Date().toISOString(),
    [`feature_${featureName}_enabled`]: true
  });
}

trackFeatureUsage('advanced_reporting');

Track Engagement Score

function updateEngagementScore(score) {
  _gs('properties', {
    engagement_score: score,
    engagement_tier: score > 80 ? 'high' : score > 50 ? 'medium' : 'low',
    score_updated_at: new Date().toISOString()
  });
}

 

 

Troubleshooting

Issue Cause Solution
Properties not appearing Nested too deeply Flatten custom object structure
Properties not updating Using identify instead of properties Use _gs('properties', {}) for updates
Data type mismatch Inconsistent types Always use same type for each property
Special characters breaking Invalid property names Use alphanumeric and underscores only
Properties overwritten Full object replacement Update specific properties only

 

 

Best Practices

  1. Identify Early: Call identify as soon as user authenticates
  2. Consistent Naming: Use snake_case for all property names
  3. Avoid PII: Don't store unnecessary personal information
  4. Type Consistency: Always use same data type for each property
  5. Update Incrementally: Use properties to update without full re-identification
  6. Document Properties: Maintain a data dictionary of all custom properties
  7. Test Thoroughly: Verify properties appear correctly in GoSquared dashboard
  8. Limit Property Count: Focus on actionable properties
  9. Use ISO Dates: Format dates as ISO 8601 strings
  10. Validate Data: Ensure data quality before sending to GoSquared

 

 

Complete Example

// Initial identification after login
_gs('identify', {
  id: user.id,
  email: user.email,
  name: user.name,
  created_at: user.created_at,
  custom: {
    plan: user.subscription.plan,
    mrr: user.subscription.mrr,
    company: user.company.name,
    role: user.role,
    department: user.department,
    is_admin: user.is_admin
  }
});

// Update properties when user takes action
document.getElementById('feature-x').addEventListener('click', function() {
  _gs('properties', {
    feature_x_enabled: true,
    feature_x_first_used: new Date().toISOString()
  });
});

// Update on page visibility change
document.addEventListener('visibilitychange', function() {
  if (document.hidden) {
    _gs('properties', {
      last_seen: new Date().toISOString()
    });
  }
});
↑ Back to top
// SYS.FOOTER