​
Integrating with Mixpanel

This guide shows you how to integrate Superline Agent Detection with Mixpanel to distinguish between human and AI agent traffic in your analytics data.

​
Why Segment AI Agent Data in Mixpanel

Mixpanel is powerful for understanding user behavior and funnels, but AI agents can distort your insights by:
  • Inflating engagement metrics
  • Creating misleading user journey patterns
  • Skewing conversion funnels and rates
  • Distorting cohort analysis
By integrating Superline Agent Detection with Mixpanel, you can:
  • Filter out or separately analyze AI agent traffic
  • Compare behavior patterns between humans and AI agents
  • Create more accurate funnels based on human-only traffic
  • Make data-driven decisions based on actual human behavior

​
Integration Steps

1

Install Required Libraries

Install both Mixpanel and Superline Agent Detection:
npm install mixpanel-browser @superline-ai/agent-detection
If you’re using script tags instead:
<!-- Mixpanel -->
<script src="https://cdn.mxpnl.com/libs/mixpanel-2-latest.min.js"></script>

<!-- Superline Agent Detection -->
<script src="https://cdn.jsdelivr.net/npm/@superline-ai/agent-detection/dist/umd/index.umd.js" defer></script>
2

Initialize Both Libraries

Initialize both libraries early in your application:
// Initialize Mixpanel
import mixpanel from 'mixpanel-browser';
mixpanel.init('YOUR_MIXPANEL_TOKEN', {
  debug: process.env.NODE_ENV !== 'production'
});

// Initialize Superline Agent Detection
import AgentDetector from '@superline-ai/agent-detection';

AgentDetector.init({
  debug: false,
  autoStart: true
});
3

Detect and Register User Properties

After collecting enough data for detection, register the result as a Mixpanel user property:
// Wait for enough interaction data
setTimeout(async () => {
  // Get detection result
  const result = await AgentDetector.finalizeDetection();
  
  // Set Mixpanel user properties
  mixpanel.people.set({
    'Is Agent': result.isAgent,
    'Agent Confidence': result.confidence
  });
  
  // Track detection event (optional)
  mixpanel.track('Agent Detection Complete', {
    is_agent: result.isAgent,
    agent_confidence: result.confidence
  });
  
  // Set super properties for all future events
  mixpanel.register({
    'Is Agent': result.isAgent,
    'Agent Confidence': result.confidence
  });
}, 5000); // 5 seconds delay
4

Create Mixpanel Cohorts

In your Mixpanel project:
  1. Go to Data Management > Cohorts
  2. Create two cohorts:
    • Human Users: where “Is Agent” equals “false”
    • AI Agents: where “Is Agent” equals “true”
5

Set Up Segmented Reports

Create segmented reports to compare humans vs. AI agents:
  1. Create any report (Insights, Funnels, Flows, etc.)
  2. Click “Add filter” or “Segment by”
  3. Select “Is Agent” as the property
  4. Compare “true” vs “false” values

​
Complete Integration Example

Here’s a comprehensive integration example that covers various scenarios: 
// mixpanel-agent-detection.js
import mixpanel from 'mixpanel-browser';
import AgentDetector from '@superline-ai/agent-detection';
// Assuming providers are imported/created:
// const metadataProvider = new BrowserMetadataProvider();
// const eventsProvider = new BrowserEventProvider();

let detector = null; // Hold detector instance

export function initializeAnalytics(mixpanelToken) {
  // Initialize Mixpanel
  mixpanel.init(mixpanelToken, {
    debug: process.env.NODE_ENV !== 'production',
    track_pageview: true
  });
  
  // Initialize Agent Detection
  // Assuming providers are available in this scope
  const metadataProvider = new BrowserMetadataProvider(); // Example
  const eventsProvider = new BrowserEventProvider(); // Example
  detector = new AgentDetector(metadataProvider, eventsProvider);
  AgentDetector.init({ autoStart: true });
  
  // Set up detection after sufficient interaction
  const detectionTimeout = setTimeout(async () => {
    try {
      await detectAndSendToMixpanel();
    } catch (error) {
      console.error('Agent detection error:', error);
      // Track detection error
      mixpanel.track('Agent Detection Error', {
        error_message: error.message
      });
    }
  }, 5000);
  
  // Attempt detection on page unload if not done yet
  window.addEventListener('beforeunload', async () => {
    clearTimeout(detectionTimeout);
    await detectAndSendToMixpanel();
  });
  
  return {
    // Expose custom tracking method that includes agent info
    track: (eventName, properties = {}) => {
      // Get agent information if available
      const agentInfo = mixpanel.get_property('Is Agent');
      
      // Only add agent props if detection has completed
      if (agentInfo !== undefined) {
        properties = {
          ...properties,
          is_agent: agentInfo
        };
      }
      
      // Track the event with agent information
      mixpanel.track(eventName, properties);
    }
  };
}

async function detectAndSendToMixpanel() {
  // Skip if already detected
  if (mixpanel.get_property('Is Agent') !== undefined) {
    return;
  }
  
  // Ensure detector is initialized
  if (!detector) {
    console.warn('AgentDetector not initialized');
    return;
  }
  
  // Get detection result
  const result = await AgentDetector.finalizeDetection();
  
  // Set Mixpanel user properties
  mixpanel.people.set({
    'Is Agent': result.isAgent,
    'Agent Confidence': result.confidence,
    'Agent Detection Time': new Date().toISOString()
  });
  
  // Register super properties for all future events
  mixpanel.register({
    'Is Agent': result.isAgent,
    'Agent Confidence': result.confidence
  });
  
  // Track detection completion
  mixpanel.track('Agent Detection Complete', {
    is_agent: result.isAgent,
    agent_confidence: result.confidence
  });
  
  // Optionally identify distinct users/agents
  if (!result.isAgent) {
    // For human users, you might want to use your normal identifier
    // mixpanel.identify(userId);
  } else {
    // For agents, you might want a special prefix
    // mixpanel.identify(`agent_${sessionId}`);
  }
}
Usage of this module: 
// In your application entry point
import { initializeAnalytics } from './mixpanel-agent-detection';

const analytics = initializeAnalytics('YOUR_MIXPANEL_TOKEN');

// Later, track events with automatic agent info
analytics.track('Button Clicked', {
  button_name: 'signup',
  page: 'homepage'
});

​
Advanced Mixpanel Features

​
Implementation Patterns

// AgentDetectionProvider.jsx
import React, { createContext, useContext, useEffect, useState } from 'react';
import mixpanel from 'mixpanel-browser';
import AgentDetector from '@superline-ai/agent-detection';

const AgentContext = createContext(null);

export function AgentDetectionProvider({ children, mixpanelToken }) {
  const [detectionResult, setDetectionResult] = useState(null);
  const [isLoading, setIsLoading] = useState(true);
  
  useEffect(() => {
    // Initialize both libraries
    mixpanel.init(mixpanelToken);
    AgentDetector.init({ autoStart: true });
    
    // Setup detection
    const timer = setTimeout(async () => {
      try {
        const result = await AgentDetector.finalizeDetection();
        setDetectionResult(result);
        
        // Send to Mixpanel
        mixpanel.people.set({
          'Is Agent': result.isAgent,
          'Agent Confidence': result.confidence
        });
        
        mixpanel.register({
          'Is Agent': result.isAgent,
          'Agent Confidence': result.confidence
        });
      } catch (error) {
        console.error(error);
      } finally {
        setIsLoading(false);
      }
    }, 5000);
    
    return () => clearTimeout(timer);
  }, [mixpanelToken]);
  
  const track = (eventName, props = {}) => {
    if (detectionResult) {
      props.is_agent = detectionResult.isAgent;
    }
    mixpanel.track(eventName, props);
  };
  
  return (
    <AgentContext.Provider value={{ 
      detectionResult, 
      isLoading, 
      track 
    }}>
      {children}
    </AgentContext.Provider>
  );
}

export const useAgentDetection = () => useContext(AgentContext);
Usage in components:
import { useAgentDetection } from './AgentDetectionProvider';

function SignupButton() {
  const { track, detectionResult } = useAgentDetection();
  
  const handleClick = () => {
    track('Signup Button Clicked');
  };
  
  // Optionally render differently for agents
  if (detectionResult?.isAgent) {
    return <button onClick={handleClick}>Sign Up (Agent UI)</button>;
  }
  
  return <button onClick={handleClick}>Sign Up</button>;
}

​
Best Practices

  1. Wait For Sufficient Data: Allow 3-5 seconds of user interaction before finalizing detection
  2. Register Super Properties: Use Mixpanel’s super properties to automatically include agent information in all events
  3. Create Segment Comparisons: Always compare key metrics between human and AI segments
  4. Use Cohorts: Create saved cohorts for humans and agents to easily apply these segments in any report
  5. Consider Confidence Thresholds: For uncertain cases (confidence around 0.4-0.6), you may want to create a third “uncertain” segment based on the Agent Confidence property, or adjust the initial detection threshold using the init option.

​
Next Steps

Google Analytics Integration

Learn how to integrate with Google Analytics

Custom Analytics

Integrate with other analytics platforms