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

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>

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
});

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

Create Mixpanel Cohorts

In your Mixpanel project:

Go to Data Management > Cohorts
Create two cohorts:
- Human Users: where “Is Agent” equals “false”
- AI Agents: where “Is Agent” equals “true”

Set Up Segmented Reports

Create segmented reports to compare humans vs. AI agents:

Create any report (Insights, Funnels, Flows, etc.)
Click “Add filter” or “Segment by”
Select “Is Agent” as the property
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

Funnel Analysis

Create separate funnels for humans and AI agents:

Go to Funnels in Mixpanel
Create your conversion funnel
Click “Segment by” and select “Is Agent”
Compare conversion rates between humans and AI agents

This reveals how conversion paths differ between humans and AI agents, and gives you a more accurate picture of your true human conversion rate.

Retention Analysis

Compare retention metrics between humans and AI agents:

Go to Retention in Mixpanel
Set up your retention analysis
Break down by “Is Agent”

This helps identify if retention metrics are being skewed by recurring AI agents.

JQL for Advanced Queries

Use Mixpanel’s JQL (JavaScript Query Language) to perform advanced analysis:

function main() {
  return Events({
    from_date: '2023-01-01',
    to_date: '2023-12-31'
  })
  .filter(function(event) {
    // Only include events from human users
    return event.properties['Is Agent'] === false;
  })
  .groupBy(['name'], mixpanel.reducer.count())
  .orderBy('value', 'desc');
}

This allows for complex filtering and analysis based on the agent detection data.

Implementation Patterns

React
Vue

// 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>;
}

// agentDetection.js
import { ref, onMounted, onBeforeUnmount } from 'vue';
import mixpanel from 'mixpanel-browser';
import AgentDetector from '@superline-ai/agent-detection';

export function useAgentDetection(mixpanelToken) {
  const detectionResult = ref(null);
  const isLoading = ref(true);
  let timer = null;
  let detector = null; // Hold detector instance
  
  onMounted(() => {
    // Assuming providers are imported/created somewhere accessible
    const metadataProvider = new BrowserMetadataProvider(); // Example
    const eventsProvider = new BrowserEventProvider(); // Example
    detector = new AgentDetector(metadataProvider, eventsProvider);
    
    // Initialize both libraries
    mixpanel.init(mixpanelToken);
    AgentDetector.init({ autoStart: true });
    
    // Setup detection
    timer = setTimeout(async () => {
      try {
        const result = await AgentDetector.finalizeDetection();
        detectionResult.value = 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 {
        isLoading.value = false;
      }
    }, 5000);
  });
  
  onBeforeUnmount(() => {
    if (timer) clearTimeout(timer);
  });
  
  const track = (eventName, props = {}) => {
    if (detectionResult.value) {
      props.is_agent = detectionResult.value.isAgent;
    }
    mixpanel.track(eventName, props);
  };
  
  return {
    detectionResult,
    isLoading,
    track
  };
}

Best Practices

Wait For Sufficient Data: Allow 3-5 seconds of user interaction before finalizing detection
Register Super Properties: Use Mixpanel’s super properties to automatically include agent information in all events
Create Segment Comparisons: Always compare key metrics between human and AI segments
Use Cohorts: Create saved cohorts for humans and agents to easily apply these segments in any report
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.

Analytics Integration

Mixpanel Integration

Integrating with Mixpanel

Why Segment AI Agent Data in Mixpanel

Integration Steps

Complete Integration Example

Advanced Mixpanel Features

Implementation Patterns

Best Practices

Next Steps

Google Analytics Integration

Custom Analytics

​Integrating with Mixpanel

​Why Segment AI Agent Data in Mixpanel

​Integration Steps

​Complete Integration Example

​Advanced Mixpanel Features

​Implementation Patterns

​Best Practices

​Next Steps

Google Analytics Integration

Custom Analytics

Integrating with Mixpanel

Why Segment AI Agent Data in Mixpanel

Integration Steps

Complete Integration Example

Advanced Mixpanel Features

Implementation Patterns

Best Practices

Next Steps