Simple Analytics Data Layer | OpsBlu Docs

Simple Analytics Data Layer

Set up the data layer for Simple Analytics — structure events, define variables, and ensure consistent tracking data.

Data Layer Setup in Simple Analytics

Simple Analytics approaches the data layer differently from traditional analytics platforms. There's no persistent "data layer" object to populate with user information. Instead, Simple Analytics focuses on ephemeral event metadata that provides context without compromising privacy. This design ensures you can track meaningful business events while respecting visitor anonymity.

Privacy-First Data Philosophy

What Simple Analytics Does NOT Track:

  • Personal identifiable information (PII)
  • Individual user IDs or session IDs
  • IP addresses
  • User fingerprints
  • Cookies or local storage
  • Cross-session user journeys

What Simple Analytics DOES Track:

  • Page views (aggregated)
  • Custom events with metadata
  • Referrer sources
  • General device/browser information
  • Geographic data (country-level)

This distinction is crucial: Simple Analytics tracks what happens, not who does it.

Event Metadata Structure

Simple Analytics events can include metadata to provide context:

Basic Event (No Metadata):

sa_event('newsletter_signup');

Event with Metadata:

sa_event('event_name', {
  key1: 'value1',
  key2: 'value2',
  key3: 123
});

Metadata Data Types:

sa_event('example_event', {
  // String values
  plan_type: 'enterprise',
  payment_method: 'credit_card',

  // Numeric values
  amount: 99.99,
  quantity: 3,

  // Boolean values (as strings or numbers)
  is_trial: 'true',
  is_upgrade: 1
});

E-Commerce Data Layer Patterns

Product Interactions:

// Product view
sa_event('product_view', {
  category: 'electronics',
  price_range: '50-100',
  on_sale: 'true'
});

// Add to cart
sa_event('add_to_cart', {
  product_category: 'headphones',
  product_price: 79.99,
  quantity: 2,
  cart_total: 159.98
});

// Remove from cart
sa_event('remove_from_cart', {
  product_category: 'headphones',
  reason: 'price_too_high'
});

Purchase Tracking:

sa_event('purchase', {
  order_value: 159.98,
  currency: 'USD',
  items_count: 2,
  payment_method: 'paypal',
  shipping_method: 'express',
  discount_applied: 'true',
  discount_amount: 20
});

Checkout Funnel Metadata:

// Checkout initiated
sa_event('checkout_started', {
  cart_value: 159.98,
  items_count: 2,
  has_discount: 'false'
});

// Shipping information
sa_event('shipping_info_added', {
  shipping_method: 'standard',
  estimated_delivery: '5-7_days'
});

// Payment information
sa_event('payment_info_added', {
  payment_type: 'card'
});

// Order confirmation
sa_event('order_completed', {
  order_value: 159.98,
  currency: 'USD'
});

SaaS Application Data Layer

Subscription Events:

// Trial signup
sa_event('trial_started', {
  plan: 'pro',
  trial_length: '14_days',
  source: 'homepage_cta'
});

// Plan selection
sa_event('plan_selected', {
  plan_type: 'enterprise',
  billing_cycle: 'annual',
  monthly_cost: 99
});

// Upgrade
sa_event('plan_upgraded', {
  from_plan: 'basic',
  to_plan: 'pro',
  increase_amount: 50
});

// Downgrade
sa_event('plan_downgraded', {
  from_plan: 'enterprise',
  to_plan: 'pro',
  reason: 'cost_reduction'
});

// Cancellation
sa_event('subscription_cancelled', {
  plan_type: 'pro',
  cancellation_reason: 'too_expensive',
  months_subscribed: 6
});

Feature Usage:

// Feature activation
sa_event('feature_enabled', {
  feature_name: 'api_access',
  feature_tier: 'enterprise'
});

// Feature usage
sa_event('feature_used', {
  feature: 'data_export',
  export_format: 'CSV',
  record_count_range: '1000-5000'
});

// Integration connected
sa_event('integration_connected', {
  integration_type: 'slack',
  connection_method: 'oauth'
});

User Milestones:

sa_event('milestone_reached', {
  milestone_type: 'projects_created',
  milestone_value: 10,
  days_since_signup_range: '30-60'
});

sa_event('usage_threshold_reached', {
  threshold_type: 'api_calls',
  threshold_amount: 10000,
  plan_type: 'pro'
});

Content Engagement Metadata

Article/Blog Metrics:

// Article read
sa_event('article_read', {
  category: 'tutorials',
  read_time_estimated: '5_min',
  author: 'staff',
  publication_date: '2024'
});

// Article completion
sa_event('article_completed', {
  category: 'tutorials',
  scroll_depth: '100',
  time_spent_range: '5-10_min'
});

// Article shared
sa_event('article_shared', {
  platform: 'twitter',
  category: 'product_updates'
});

Video Engagement:

// Video play
sa_event('video_play', {
  video_category: 'tutorial',
  video_length_range: '5-10_min',
  auto_play: 'false'
});

// Video milestone
sa_event('video_progress', {
  video_category: 'tutorial',
  progress_percent: 50,
  playback_speed: '1.5x'
});

// Video completed
sa_event('video_complete', {
  video_category: 'tutorial',
  completion_rate: '100',
  watched_with_subtitles: 'true'
});

Download Tracking:

sa_event('resource_downloaded', {
  resource_type: 'whitepaper',
  file_format: 'PDF',
  topic_category: 'security',
  file_size_range: '1-5_MB'
});

Form Interaction Metadata

Form Engagement:

// Form started
sa_event('form_started', {
  form_type: 'contact',
  form_location: 'footer',
  fields_total: 8
});

// Form submitted
sa_event('form_submitted', {
  form_type: 'contact',
  fields_completed: 8,
  time_to_complete_range: '60-120_sec'
});

// Form abandoned
sa_event('form_abandoned', {
  form_type: 'checkout',
  fields_completed: 3,
  fields_total: 8,
  abandonment_stage: 'payment_info'
});

// Form error
sa_event('form_error', {
  form_type: 'signup',
  error_field: 'email',
  error_type: 'invalid_format'
});

Marketing Campaign Tracking

Campaign Attribution:

// Campaign landing
sa_event('campaign_landing', {
  campaign_name: 'summer_sale_2024',
  campaign_medium: 'email',
  campaign_source: 'newsletter'
});

// Campaign conversion
sa_event('campaign_conversion', {
  campaign_name: 'summer_sale_2024',
  conversion_type: 'purchase',
  conversion_value_range: '50-100'
});

Email Marketing:

// Email link clicked
sa_event('email_link_clicked', {
  email_campaign: 'product_launch',
  link_position: 'cta_button',
  subscriber_segment: 'active_users'
});

Data Layer Best Practices

1. Use Consistent Naming

// GOOD: Consistent naming
sa_event('newsletter_signup', { source: 'footer' });
sa_event('product_purchased', { category: 'electronics' });
sa_event('video_completed', { category: 'tutorial' });

// BAD: Inconsistent naming
sa_event('nlSignup', { source: 'footer' });
sa_event('bought', { cat: 'electronics' });
sa_event('vidDone', { category: 'tutorial' });

Naming Convention:

  • Use snake_case for event names: cart_abandoned, trial_started
  • Use descriptive keys: payment_method not pm
  • Be specific: trial_started not just trial
  • Group related events: checkout_started, checkout_completed

2. Structure Metadata Consistently

Keep similar events using the same metadata structure:

// All purchase events use same structure
sa_event('purchase', {
  order_value: 99.99,
  currency: 'USD',
  items_count: 2,
  payment_method: 'stripe'
});

sa_event('purchase', {
  order_value: 149.99,
  currency: 'USD',
  items_count: 1,
  payment_method: 'paypal'
});

3. Use Value Ranges Instead of Exact Values

For privacy and aggregation:

// GOOD: Use ranges
sa_event('purchase', {
  value_range: '50-100',
  items_range: '1-5'
});

// AVOID: Exact values that might identify users
sa_event('purchase', {
  exact_value: 87.32,  // Too specific
  user_id: '12345'      // Never include user IDs
});

4. Include Business Context

sa_event('feature_used', {
  feature: 'export',
  format: 'CSV',
  record_count_range: '1000-5000',
  user_plan: 'pro',  // Business context
  is_trial: 'false'  // Business context
});

5. Avoid PII in Metadata

// BAD: Contains PII
sa_event('signup', {
  email: 'user@example.com',  // Never
  name: 'John Doe',            // Never
  ip_address: '192.168.1.1'   // Never
});

// GOOD: Generic metadata
sa_event('signup', {
  source: 'landing_page',
  plan_selected: 'free',
  registration_method: 'google_oauth'
});

Metadata Limitations

Character Limits:

  • Event names: Keep concise (< 50 characters recommended)
  • Metadata keys: Short and descriptive (< 30 characters)
  • Metadata values: Brief and meaningful (< 100 characters)

Metadata Count:

  • Limit to 5-10 metadata fields per event
  • Focus on most relevant context
  • Avoid redundant information

Data Types:

  • Strings: Most common, best for categories
  • Numbers: For values, counts, percentages
  • Booleans: Use strings ('true'/'false') or numbers (1/0)

Testing Metadata

Verification Script:

function testMetadata() {
  const testEvents = [
    { name: 'purchase', data: { value: 99, currency: 'USD' } },
    { name: 'signup', data: { plan: 'pro', source: 'homepage' } },
    { name: 'feature_used', data: { feature: 'export', format: 'CSV' } }
  ];

  testEvents.forEach(({ name, data }) => {
    console.log(`Testing: ${name}`, data);
    sa_event(name, data);
  });

  console.log('Check dashboard for test events');
}

// Run tests
testMetadata();

Dashboard Verification:

  1. Fire test events with known metadata
  2. Go to Simple Analytics dashboard
  3. Click "Events" tab
  4. Click test event name
  5. Verify metadata appears correctly
  6. Check metadata value breakdowns

Metadata Schema Validation

// Define expected schemas
const EVENT_SCHEMAS = {
  purchase: {
    required: ['order_value', 'currency'],
    optional: ['items_count', 'payment_method']
  },
  signup: {
    required: ['plan'],
    optional: ['source', 'referrer']
  }
};

function validateAndTrack(eventName, eventData) {
  const schema = EVENT_SCHEMAS[eventName];

  if (schema) {
    // Check required fields
    const missingFields = schema.required.filter(
      field => !(field in eventData)
    );

    if (missingFields.length > 0) {
      console.warn(`Missing required fields for ${eventName}:`, missingFields);
    }
  }

  // Track event
  sa_event(eventName, eventData);
}

// Usage
validateAndTrack('purchase', {
  order_value: 99.99,
  currency: 'USD',
  payment_method: 'stripe'
});

GTM Data Layer Integration

If using Google Tag Manager, forward to Simple Analytics:

// Listen to GTM dataLayer pushes
window.dataLayer = window.dataLayer || [];
window.dataLayer.push = function(obj) {
  Array.prototype.push.call(window.dataLayer, obj);

  // Forward specific events to Simple Analytics
  const FORWARD_EVENTS = ['purchase', 'signup', 'add_to_cart'];

  if (obj.event && FORWARD_EVENTS.includes(obj.event)) {
    const metadata = {
      ...obj
    };
    delete metadata.event; // Remove GTM event property

    sa_event(obj.event, metadata);
  }
};

Migration from Other Platforms

From Google Analytics Enhanced Ecommerce:

// GA4 Enhanced Ecommerce
gtag('event', 'purchase', {
  transaction_id: 'T12345',
  value: 99.99,
  currency: 'USD',
  items: [...]
});

// Simple Analytics equivalent (simplified, privacy-focused)
sa_event('purchase', {
  value_range: '50-100',
  currency: 'USD',
  items_count: 2
  // Note: No transaction ID or individual item details
});

From Segment:

// Segment
analytics.track('Product Purchased', {
  product_id: '123',
  price: 99.99,
  category: 'electronics'
});

// Simple Analytics
sa_event('product_purchased', {
  price_range: '50-100',
  category: 'electronics'
  // Note: Product ID removed for privacy
});

Viewing Metadata in Dashboard

Access Event Metadata:

  1. Go to Simple Analytics dashboard
  2. Click "Events" in sidebar
  3. Click on event name
  4. See metadata breakdown
  5. View frequency of each metadata value
  6. Export metadata for analysis

Metadata Analysis:

  • See which metadata values are most common
  • Identify patterns in user behavior
  • Filter events by specific metadata values
  • Track metadata trends over time

Summary

Simple Analytics' data layer approach is fundamentally different:

  • No persistent user data: Metadata is event-specific
  • Privacy by design: Never include PII
  • Aggregate analysis: Metadata helps segment events, not users
  • Simple structure: Just event name + optional metadata object
  • Business insights: Focus on actionable context

This approach gives you valuable insights into how your product is used while maintaining user privacy and complying with data protection regulations.

返回顶部