Frontend Analytics Integration Guide¶

import axios from 'axios';

const API_BASE_URL = import.meta.env.VITE_API_BASE_URL || 'http://localhost:8000';

/**
 * Track user activity in the backend analytics system
 * @param {string} activityType - Type of activity (page_view, button_click, search, etc.)
 * @param {string} pageUrl - Current page URL or route
 * @param {Object} extraData - Additional context (optional)
 */
export const trackActivity = async (activityType, pageUrl, extraData = {}) => {
  try {
    await axios.post(
      `${API_BASE_URL}/api/v1/analytics/user-activity`,
      {
        activity_type: activityType,
        page_url: pageUrl,
        extra_data: extraData
      },
      {
        withCredentials: true, // Important: sends auth cookie
        timeout: 2000 // Don't block UI if analytics is slow
      }
    );
  } catch (error) {
    // Silently fail - don't break user experience if analytics fails
    console.debug('Analytics tracking failed:', error.message);
  }
};

/**
 * Track search queries
 * @param {string} query - Search query text
 * @param {string} pageUrl - Where the search happened
 * @param {number} resultsCount - Number of results (optional)
 */
export const trackSearch = async (query, pageUrl, resultsCount = null) => {
  const extraData = resultsCount !== null ? { results_count: resultsCount } : {};
  await trackActivity('search', pageUrl, { search_query: query, ...extraData });
};

/**
 * Track errors encountered by users
 * @param {string} errorMessage - Error message shown to user
 * @param {string} pageUrl - Where error occurred
 * @param {string} errorType - Type of error (api_error, validation_error, etc.)
 */
export const trackError = async (errorMessage, pageUrl, errorType = 'client_error') => {
  try {
    await axios.post(
      `${API_BASE_URL}/api/v1/analytics/error`,
      {
        category: errorType,
        severity: 'error',
        message: errorMessage,
        extra_data: { page_url: pageUrl }
      },
      {
        withCredentials: true,
        timeout: 2000
      }
    );
  } catch (error) {
    console.debug('Error tracking failed:', error.message);
  }
};

// Example: frontend/src/App.jsx or similar
import { useEffect } from 'react';
import { useLocation } from 'react-router-dom';
import { trackActivity } from './utils/analytics';

function App() {
  const location = useLocation();

  // Track page views on route changes
  useEffect(() => {
    trackActivity('page_view', location.pathname);
  }, [location.pathname]);

  return (
    // ... existing App component
  );
}

// frontend/src/pages/Devices.jsx (or similar)
import { trackActivity } from '../utils/analytics';

function DevicesPage() {
  const handleDeviceAction = async (deviceId, action) => {
    // Track the action
    await trackActivity('button_click', '/devices', {
      action: action,
      device_id: deviceId
    });

    // ... existing device action code
  };

  const handleFilterChange = async (filterType, filterValue) => {
    await trackActivity('filter_applied', '/devices', {
      filter_type: filterType,
      filter_value: filterValue
    });

    // ... existing filter code
  };

  return (
    // ... existing component
  );
}

// frontend/src/pages/Jobs.jsx (or similar)
import { trackActivity } from '../utils/analytics';

function JobsPage() {
  const handleCreateJob = async (jobData) => {
    await trackActivity('form_submit', '/jobs', {
      action: 'create_job',
      job_type: jobData.action
    });

    // ... existing job creation code
  };

  return (
    // ... existing component
  );
}

// Example: Search component
import { trackSearch } from '../utils/analytics';

function SearchBar() {
  const handleSearch = async (searchQuery) => {
    // Track the search
    await trackSearch(searchQuery, window.location.pathname);

    // ... existing search code
    const results = await performSearch(searchQuery);

    // Optionally track results count
    await trackSearch(searchQuery, window.location.pathname, results.length);
  };

  return (
    // ... existing search component
  );
}

// Example: API error handler
import { trackError } from '../utils/analytics';

// In your axios interceptor or error boundary
axios.interceptors.response.use(
  response => response,
  async error => {
    if (error.response) {
      // Track API errors
      await trackError(
        error.response.data.detail || 'API request failed',
        window.location.pathname,
        'api_error'
      );
    }
    return Promise.reject(error);
  }
);

// Or in individual components
const handleSubmit = async (formData) => {
  try {
    await submitData(formData);
  } catch (error) {
    await trackError(
      error.message,
      '/form-page',
      'form_submission_error'
    );
    // Show error to user
  }
};