Interaction tracking allows you to record how users engage with search results, enabling personalized ranking, relevance improvement, and usage analytics.

​
Overview

In Mixpeek, interactions represent how users engage with search results. By tracking these interactions, you can gather valuable data to improve search relevance, personalize results, and gain insights into user behavior and content performance.

User Engagement Data

Record how users interact with search results, including clicks, views, and conversions

Relevance Signals

Use interaction data as signals to improve search relevance and personalization

​
Types of Interactions

Mixpeek supports several types of user interactions that you can track:

​
Recording Interactions

You can record interactions using the Mixpeek API:

from mixpeek import Mixpeek

mp = Mixpeek(api_key="YOUR_API_KEY")

# Record a click interaction
interaction = mp.interactions.create(
    namespace_id="ns_abc123",
    type="click",
    document_id="doc_def456",
    user_id="user_ghi789",
    session_id="session_jkl012",
    search_id="search_mno345",
    position=3,
    metadata={
        "query": "wireless headphones",
        "device": "mobile",
        "page": "search_results"
    }
)

print(f"Recorded interaction: {interaction['interaction_id']}")

​
Interaction Parameters

ParameterTypeDescription
namespace_idstringID of the namespace containing the document
typestringInteraction type: “click”, “view”, “conversion”, or custom
document_idstringID of the document the user interacted with

Interactions can be used to personalize and improve search results:

​
Personalized Retriever

{
  "stages": [
    {
      "name": "vector_search",
      "type": "vector",
      "collection_id": "col_products",
      "index": "multimodal",
      "limit": 50
    },
    {
      "name": "personalized_rank",
      "type": "rank",
      "input": "vector_search.results",
      "weights": {
        "vector_score": 0.6,
        "user_interactions": 0.4
      },
      "parameters": {
        "user_id": "{user_id}",
        "interaction_types": ["click", "conversion"],
        "recency_decay": 0.1
      },
      "limit": 20
    }
  ]
}

​
User-Based Filtering

# Search with user-based filtering
results = mp.retrievers.search(
    retriever_id="ret_tuv901",
    query={
        "text": "running shoes"
    },
    user_context={
        "user_id": "user_ghi789",
        "use_interaction_history": True,
        "interaction_types": ["click", "view", "conversion"],
        "exclude_previously_interacted": False,
        "interaction_recency_weight": 0.2
    }
)

​
Tracking Interactions Client-Side

For web applications, you can use the Mixpeek JavaScript SDK to track interactions:

// Initialize the SDK with your API key
const mp = new Mixpeek({
  apiKey: 'YOUR_API_KEY',
  namespace: 'ns_abc123'
});

// Get search results
const results = await mp.retrievers.search({
  retriever_id: "ret_def456",
  query: {
    text: "wireless headphones"
  }
});

// Store the search ID for tracking interactions
const searchId = results.search_id;

// Add click event listeners to search results
document.querySelectorAll('.search-result').forEach((element, index) => {
  element.addEventListener('click', async () => {
    const documentId = element.getAttribute('data-document-id');
    
    // Record click interaction
    await mp.interactions.create({
      type: "click",
      document_id: documentId,
      search_id: searchId,
      position: index + 1,
      user_id: getCurrentUserId(), // Your function to get the user ID
      session_id: getSessionId(),  // Your function to get the session ID
      metadata: {
        query: "wireless headphones",
        device: getDeviceType(),  // Your function to detect device type
        page: "search_results"
      }
    });
    
    // Navigate to the result page
    window.location.href = element.getAttribute('href');
  });
});

​
Analytics and Reporting

​
User Interaction Tracking

Monitor how users interact with your retrieval system:

Key Metrics

  • Query volume (total, by time period, by user segment)
  • Session metrics (duration, queries per session)
  • Most frequent queries and search patterns
  • Abandonment rates and search refinements

Implementation

# Generate usage report for the last 30 days
usage_report = analytics.generate_report(
  report_type="usage",
  time_range={"days": 30},
  segments=["user_type", "device_type"]
)

# Export report data
analytics.export_to_csv(usage_report, "monthly_usage_analytics.csv")

​
Best Practices

1

Track Consistently

Implement interaction tracking consistently across your application to collect comprehensive data.

2

Include Context

Capture relevant contextual information in the metadata field to make interactions more valuable for analysis.

3

Balance Privacy

Respect user privacy by anonymizing user identifiers where appropriate and complying with relevant regulations.

4

Optimize Volume

For high-traffic applications, consider batching interaction records or sampling to manage data volume.

Interaction data can grow rapidly in high-traffic applications. Consider implementing data retention policies and monitoring storage usage.

​
Implementation Strategies

Basic Implementation

  • Track clicks on search results
  • Use document position data
  • Include user and session IDs
  • Store basic query information

Intermediate Implementation

  • Track clicks, views, and conversions
  • Measure view duration and engagement depth
  • Include device and page context
  • Implement client-side tracking with JS SDK

Advanced Implementation

  • Track custom interaction types
  • Implement personalized ranking based on history
  • Use interaction data for A/B testing
  • Analyze interaction patterns for recommendations

Enterprise Implementation

  • Integrate with data warehouses
  • Implement comprehensive reporting
  • Use interaction data for model training
  • Create personalized content recommendations

​
API Reference

For complete details on working with interactions, see our Interactions API Reference.