Menu ▾ ▴

INTEGRATION_GUIDE

Robert Trenaman

Integration Guide

This comprehensive guide covers various integration methods for the Open Source Site Tracking platform, enabling you to incorporate analytics into your existing systems and workflows.

Overview

The Open Source Site Tracking platform offers multiple integration options:

  • JavaScript SDK: Client-side tracking
  • REST API: Server-side integration
  • Webhooks: Event notifications
  • Third-party Tools: Popular service integrations
  • Custom Solutions: Tailored integration approaches

JavaScript SDK Integration

Basic Setup

<!-- Add to your website's <head> section -->
<script src="https://your-domain.com/tracking.js" data-project-id="your-project-id"></script>

Advanced Configuration

// Initialize with custom configuration
SiteTracking.init({
  projectId: 'your-project-id',
  apiEndpoint: 'https://your-domain.com/api',
  tracking: {
    pageViews: true,
    clicks: true,
    scrolls: true,
    forms: true,
    customEvents: true
  },
  privacy: {
    respectDoNotTrack: true,
    anonymizeIp: true,
    cookieConsent: true
  },
  performance: {
    sampleRate: 1.0,
    batchSize: 10,
    flushInterval: 5000
  }
});

Custom Event Tracking

// Track custom events
SiteTracking.track('button-click', {
  buttonId: 'signup-button',
  page: '/landing-page',
  userSegment: 'new-user'
});

// Track form submissions
SiteTracking.track('form-submit', {
  formId: 'contact-form',
  fields: ['name', 'email', 'message'],
  success: true
});

// Track user interactions
SiteTracking.track('feature-use', {
  feature: 'advanced-search',
  action: 'filter-applied',
  filters: ['date-range', 'category']
});

E-commerce Integration

// Track product views
SiteTracking.track('product-view', {
  productId: 'prod-123',
  productName: 'Analytics Pro',
  category: 'software',
  price: 99.99,
  currency: 'USD'
});

// Track purchases
SiteTracking.track('purchase', {
  orderId: 'order-456',
  products: [
    {
      productId: 'prod-123',
      quantity: 1,
      price: 99.99
    }
  ],
  total: 99.99,
  currency: 'USD'
});

REST API Integration

Authentication

import requests

# API authentication
headers = {
    'Authorization': 'Bearer your-api-token',
    'Content-Type': 'application/json'
}

# Base URL
base_url = 'https://your-domain.com/api/v1'

Project Management

# Create new project
project_data = {
    'name': 'My Project',
    'description': 'Project description',
    'repository_url': 'https://github.com/user/repo',
    'tracking_domain': 'mydomain.com'
}

response = requests.post(
    f'{base_url}/projects',
    headers=headers,
    json=project_data
)

project = response.json()
project_id = project['id']

Analytics Data Retrieval

# Get analytics overview
response = requests.get(
    f'{base_url}/analytics/{project_id}/overview',
    headers=headers,
    params={
        'start_date': '2024-01-01',
        'end_date': '2024-01-31',
        'metrics': ['page_views', 'unique_visitors', 'bounce_rate']
    }
)

analytics = response.json()

Event Tracking

# Track events from server
event_data = {
    'event_type': 'server_action',
    'properties': {
        'action': 'user_login',
        'user_id': 'user-123',
        'timestamp': '2024-01-15T10:30:00Z'
    }
}

response = requests.post(
    f'{base_url}/events/{project_id}',
    headers=headers,
    json=event_data
)

Webhook Integration

Webhook Configuration

# Configure webhooks
webhook_config = {
    'url': 'https://your-app.com/webhooks/analytics',
    'events': [
        'page_view',
        'user_signup',
        'conversion',
        'error'
    ],
    'secret': 'your-webhook-secret',
    'active': True
}

response = requests.post(
    f'{base_url}/webhooks/{project_id}',
    headers=headers,
    json=webhook_config
)

Webhook Handler

from flask import Flask, request, jsonify
import hmac
import hashlib

app = Flask(__name__)

@app.route('/webhooks/analytics', methods=['POST'])
def handle_analytics_webhook():
    # Verify webhook signature
    signature = request.headers.get('X-Signature')
    payload = request.data

    expected_signature = hmac.new(
        'your-webhook-secret'.encode(),
        payload,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected_signature):
        return jsonify({'error': 'Invalid signature'}), 401

    # Process webhook data
    event = request.json

    if event['event_type'] == 'user_signup':
        handle_user_signup(event)
    elif event['event_type'] == 'conversion':
        handle_conversion(event)

    return jsonify({'status': 'success'})

def handle_user_signup(event):
    # Process user signup event
    user_data = event['properties']
    # Add user to CRM, send welcome email, etc.

def handle_conversion(event):
    # Process conversion event
    conversion_data = event['properties']
    # Update analytics, notify team, etc.

Third-party Integrations

Google Analytics Integration

// Send data to Google Analytics
SiteTracking.on('track', function(event) {
  if (window.gtag) {
    gtag('event', event.type, {
      'event_category': 'Site Tracking',
      'event_label': event.properties.action,
      'value': event.properties.value
    });
  }
});

Segment Integration

// Send data to Segment
SiteTracking.on('track', function(event) {
  if (window.analytics) {
    analytics.track(event.type, event.properties);
  }
});

Mixpanel Integration

// Send data to Mixpanel
SiteTracking.on('track', function(event) {
  if (window.mixpanel) {
    mixpanel.track(event.type, event.properties);
  }
});

HubSpot Integration

# Sync data with HubSpot
import hubspot

def sync_to_hubspot(event_data):
    client = hubspot.Client.create(access_token='your-hubspot-token')

    if event_data['event_type'] == 'user_signup':
        # Create or update contact
        contact_data = {
            'properties': [
                {'property': 'email', 'value': event_data['properties']['email']},
                {'property': 'source', 'value': 'site-tracking'}
            ]
        }

        client.crm.contacts.basic_api.create(contact_data)

Framework Integrations

React Integration

// React component integration
import { useEffect } from 'react';
import SiteTracking from 'site-tracking-sdk';

function AnalyticsProvider({ children, projectId }) {
  useEffect(() => {
    SiteTracking.init({
      projectId: projectId,
      tracking: {
        pageViews: true,
        clicks: true
      }
    });
  }, [projectId]);

  return children;
}

// Custom hook for tracking
function useAnalytics() {
  const track = (eventType, properties) => {
    SiteTracking.track(eventType, properties);
  };

  return { track };
}

// Usage in components
function MyComponent() {
  const { track } = useAnalytics();

  const handleClick = () => {
    track('button-click', { buttonId: 'my-button' });
  };

  return <button onClick={handleClick}>Click me</button>;
}

Vue.js Integration

// Vue plugin
import SiteTracking from 'site-tracking-sdk';

const AnalyticsPlugin = {
  install(app, options) {
    SiteTracking.init(options);

    app.config.globalProperties.$track = (eventType, properties) => {
      SiteTracking.track(eventType, properties);
    };

    app.provide('analytics', SiteTracking);
  }
};

// Usage in Vue app
app.use(AnalyticsPlugin, {
  projectId: 'your-project-id'
});

// In components
export default {
  methods: {
    handleClick() {
      this.$track('button-click', { buttonId: 'my-button' });
    }
  }
};

Angular Integration

// Angular service
import { Injectable } from '@angular/core';
import SiteTracking from 'site-tracking-sdk';

@Injectable({
  providedIn: 'root'
})
export class AnalyticsService {
  constructor() {
    SiteTracking.init({
      projectId: 'your-project-id'
    });
  }

  track(eventType: string, properties: object): void {
    SiteTracking.track(eventType, properties);
  }
}

// Usage in components
@Component({
  selector: 'app-my-component',
  template: '<button (click)="handleClick()">Click me</button>'
})
export class MyComponent {
  constructor(private analytics: AnalyticsService) {}

  handleClick(): void {
    this.analytics.track('button-click', { buttonId: 'my-button' });
  }
}

Backend Integration Examples

Node.js Integration

const express = require('express');
const axios = require('axios');

const app = express();

// Middleware for tracking
app.use((req, res, next) => {
  // Track API requests
  axios.post('https://your-domain.com/api/v1/events/your-project-id', {
    event_type: 'api_request',
    properties: {
      method: req.method,
      path: req.path,
      user_agent: req.get('User-Agent'),
      ip: req.ip
    }
  }, {
    headers: {
      'Authorization': 'Bearer your-api-token'
    }
  }).catch(console.error);

  next();
});

// Custom event tracking
app.post('/track', async (req, res) => {
  try {
    const response = await axios.post(
      'https://your-domain.com/api/v1/events/your-project-id',
      req.body,
      {
        headers: {
          'Authorization': 'Bearer your-api-token'
        }
      }
    );

    res.json(response.data);
  } catch (error) {
    res.status(500).json({ error: error.message });
  }
});

Python Integration

from flask import Flask, request
import requests

app = Flask(__name__)

# Configuration
SITE_TRACKING_API = 'https://your-domain.com/api/v1'
API_TOKEN = 'your-api-token'
PROJECT_ID = 'your-project-id'

def track_event(event_type, properties):
    """Track event with Site Tracking API"""
    try:
        requests.post(
            f'{SITE_TRACKING_API}/events/{PROJECT_ID}',
            headers={
                'Authorization': f'Bearer {API_TOKEN}',
                'Content-Type': 'application/json'
            },
            json={
                'event_type': event_type,
                'properties': properties
            }
        )
    except Exception as e:
        app.logger.error(f"Tracking error: {e}")

@app.route('/api/action', methods=['POST'])
def handle_action():
    """Handle custom action tracking"""
    data = request.get_json()

    track_event('custom_action', {
        'action': data.get('action'),
        'user_id': data.get('user_id'),
        'timestamp': datetime.utcnow().isoformat()
    })

    return {'status': 'success'}

Mobile App Integration

React Native Integration

import { NativeModules, Platform } from 'react-native';

const SiteTracking = NativeModules.SiteTracking;

// Initialize tracking
SiteTracking.init({
  projectId: 'your-project-id',
  platform: Platform.OS
});

// Track events
SiteTracking.track('screen_view', {
  screen_name: 'HomeScreen',
  user_id: 'user-123'
});

SiteTracking.track('button_tap', {
  button_id: 'login-button',
  screen_name: 'LoginScreen'
});

iOS Integration (Swift)

import SiteTrackingSDK

class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

        // Initialize Site Tracking
        SiteTracking.shared.initialize(projectId: "your-project-id")

        return true
    }
}

// Track events in view controllers
class ViewController: UIViewController {

    override func viewDidLoad() {
        super.viewDidLoad()

        // Track screen view
        SiteTracking.shared.track("screen_view", properties: [
            "screen_name": "MainViewController"
        ])
    }

    @IBAction func buttonTapped(_ sender: UIButton) {
        // Track button tap
        SiteTracking.shared.track("button_tap", properties: [
            "button_id": sender.accessibilityIdentifier ?? "unknown"
        ])
    }
}

Android Integration (Kotlin)

import com.sitetracking.sdk.SiteTracking

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)

        // Initialize Site Tracking
        SiteTracking.initialize(this, "your-project-id")

        // Track screen view
        SiteTracking.track("screen_view", mapOf(
            "screen_name" to "MainActivity"
        ))
    }

    fun onButtonClick(view: View) {
        // Track button click
        SiteTracking.track("button_click", mapOf(
            "button_id" to view.id.toString()
        ))
    }
}

Testing Integration

Unit Testing

// Mock Site Tracking for testing
const mockSiteTracking = {
  init: jest.fn(),
  track: jest.fn()
};

jest.mock('site-tracking-sdk', () => mockSiteTracking);

test('should track button click', () => {
  const { track } = useAnalytics();

  track('button-click', { buttonId: 'test-button' });

  expect(mockSiteTracking.track).toHaveBeenCalledWith('button-click', {
    buttonId: 'test-button'
  });
});

Integration Testing

import pytest
import requests

def test_api_integration():
    """Test API integration with Site Tracking"""

    response = requests.post(
        'https://your-domain.com/api/v1/events/test-project',
        headers={'Authorization': 'Bearer test-token'},
        json={
            'event_type': 'test_event',
            'properties': {'test': True}
        }
    )

    assert response.status_code == 200
    assert response.json()['status'] == 'success'

Best Practices

Performance Considerations

  1. Async Tracking: Use non-blocking tracking calls
  2. Batch Events: Group multiple events together
  3. Sampling: Use appropriate sampling rates
  4. Caching: Cache API responses when possible

Privacy Compliance

  1. Consent Management: Respect user preferences
  2. Data Minimization: Collect only necessary data
  3. Anonymization: Remove personally identifiable information
  4. GDPR Compliance: Follow data protection regulations

Error Handling

  1. Graceful Degradation: Handle API failures gracefully
  2. Retry Logic: Implement retry mechanisms
  3. Logging: Log tracking errors for debugging
  4. Fallbacks: Provide fallback tracking methods

Security

  1. API Keys: Secure API key storage
  2. HTTPS: Use secure connections
  3. Input Validation: Validate tracking data
  4. Access Control: Implement proper access controls

Troubleshooting

Common Issues

  1. Tracking Not Working: Verify initialization and configuration
  2. Data Not Appearing: Check API connectivity and authentication
  3. Performance Issues: Optimize tracking implementation
  4. Privacy Concerns: Review data collection practices

Debug Tools

// Enable debug mode
SiteTracking.debug(true);

// Check tracking status
console.log(SiteTracking.getStatus());

// View queued events
console.log(SiteTracking.getQueuedEvents());

This integration guide provides comprehensive coverage of various integration methods, enabling you to successfully incorporate the Open Source Site Tracking platform into your existing systems and workflows.

auth0 logo