Skip to main content

Get Recommendations

After uploading your users to the SplitScreen platform, you can start getting personalized matchmaking recommendations. The system analyzes user profiles and preferences to suggest compatible players for your users.

Getting User Recommendations​

Make a GET request to the /v1/users/{user_id}/recommendations endpoint, replacing {user_id} with the ID of the user you want to get recommendations for.

Request:

curl -X GET \
  "https://api.splitscreen-example.com/v1/users/user123/recommendations?count=10" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Response:

{
  "recommendations": [
    {
      "client_user_id": "client123:user456",
      "display_name": "PlayerTwo",
      "overall_score": 0.85,
      "score_breakdown": {
        "games": 0.9,
        "schedule": 0.8,
        "location": 0.75,
        "genres": 0.9,
        "personality": 0.85,
        "yee_gamer_motivation": 0.78
      }
    },
    {
      "client_user_id": "client123:user789",
      "display_name": "PlayerThree",
      "overall_score": 0.72,
      "score_breakdown": {
        "games": 0.7,
        "schedule": 0.8,
        "location": 0.65,
        "genres": 0.7,
        "personality": 0.75,
        "yee_gamer_motivation": 0.68
      }
    }
  ]
}

Query Parameters​

  • count (optional): Number of recommendations to return (default: 10, max: 50)
  • min_score (optional): Minimum match score threshold (0.0 to 1.0)
  • game_type (optional): Filter recommendations by specific game type

Example with parameters:

curl -X GET \
  "https://api.splitscreen-example.com/v1/users/user123/recommendations?count=5&min_score=0.7&game_type=fps" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Understanding Match Scores​

The overall_score is a value between 0.0 and 1.0 that indicates how well two users are matched:

  • 0.9 - 1.0: Excellent match
  • 0.7 - 0.9: Good match
  • 0.5 - 0.7: Moderate match
  • 0.0 - 0.5: Poor match

The score is calculated based on various factors including:

  • Games: Compatibility based on shared games and playtime patterns
  • Schedule: Availability matching based on timezone and time slots
  • Location: Geographic proximity for latency optimization
  • Genres: Game genre preference alignment
  • Personality: MBTI personality type compatibility
  • Yee Gamer Motivation: Gaming motivation profile similarity
  • Steam data compatibility (when Steam integration is enabled)

Score Breakdown​

The score_breakdown object provides detailed breakdown of why users are matched:

  • games: Compatibility based on shared games and playtime patterns
  • schedule: Availability matching based on timezone and time slots
  • location: Geographic proximity for latency optimization
  • genres: Game genre preference alignment
  • personality: MBTI personality type compatibility (INTJ, ENFP, etc.)
  • yee_gamer_motivation: Gaming motivation profile similarity across 12 dimensions
  • steam_compatibility: Steam data matching score (when enabled)

Steam Integration​

When Steam integration is enabled for your client, recommendations are significantly enhanced with real gaming data:

Enhanced Scoring​

  • Game Library Analysis: Matches based on actual owned games
  • Genre Preferences: Uses Steam genre data for better compatibility
  • Playtime Patterns: Considers gaming habits and preferences
  • Steam Insights: Additional scoring factors from Steam data

Steam Data in Recommendations​

{
  "steam_insights": {
    "shared_games": 15,
    "genre_overlap": 0.87,
    "play_style_match": "competitive"
  }
}

For detailed information about enabling and configuring Steam integration, see the Steam Integration Guide.

Yee's Gamer Motivation Model​

PlaySync leverages Yee's Gamer Motivation Model to provide more accurate matchmaking by understanding what drives your users to play games.

What It Measures​

The model analyzes 12 key gaming motivations that influence player behavior and preferences:

  • Power: Desire for status, control, and dominance
  • Story: Interest in narrative and character development
  • Design: Appreciation for aesthetics and creativity
  • Fantasy: Desire for escapism and role-playing
  • Strategy: Preference for tactical thinking and planning
  • Challenge: Seeking difficulty and skill mastery
  • Community: Desire for social interaction and teamwork
  • Discovery: Interest in exploration and learning
  • Completion: Drive to finish games and collect achievements
  • Excitement: Seeking adrenaline and fast-paced action
  • Competition: Desire to win and outperform others
  • Destruction: Enjoyment of chaos and mayhem

How It Improves Matchmaking​

When you provide Yee's gamer motivation scores for your users, PlaySync can:

  • Match Compatible Players: Find users with similar gaming motivations
  • Reduce Toxicity: Avoid matching players with conflicting play styles
  • Improve User Satisfaction: Users are more likely to enjoy playing with compatible teammates
  • Enhance Retention: Better matches lead to longer user engagement

Integration with Quantic Foundry​

We have partnered with Quantic Foundry to support the integration of Yee's Gamer Motivation Model survey in your applications. This allows you to:

  1. Collect Motivation Data: Use Quantic Foundry's validated survey to gather user motivation scores
  2. Improve Matchmaking: Provide more accurate recommendations based on gaming psychology
  3. Enhanced User Experience: Help users find players with compatible gaming motivations

Score Breakdown​

The yee_gamer_motivation score in the breakdown represents how similar two users' gaming motivations are across all 12 dimensions. A higher score indicates more compatible gaming preferences.

Example:

{
  "yee_gamer_motivation": 0.78,
  "personality": 0.85,
  "games": 0.9
}

For more information about implementing Yee's Gamer Motivation Model in your application, contact us or visit Quantic Foundry's resources.

Real-time Recommendations​

For real-time matchmaking, you can call the recommendations endpoint whenever a user is looking for a match. The system will:

  1. Analyze the user's current profile
  2. Find other users who are also looking for matches
  3. Return the best matches based on compatibility

Example for real-time matchmaking:

curl -X GET \
  "https://api.playsync.com/v1/users/user123/recommendations?count=3&min_score=0.8" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Batch Recommendations​

If you need recommendations for multiple users at once, you can make separate requests for each user. The system optimizes for individual user matching rather than batch processing.

Error Handling​

Common error responses:

User not found:

{
  "error": "Resource not found",
  "message": "User with ID 'user123' does not exist"
}

Insufficient data:

{
  "error": "Insufficient user data",
  "message": "User profile needs more information for accurate recommendations"
}

Invalid parameters:

{
  "error": "Invalid parameters",
  "message": "Count must be between 1 and 50"
}

Example: Complete Recommendation Flow​

# 1. Get your access token (see Client Registration guide)
curl -X POST https://api.playsync.com/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "your-client-id",
    "api_key": "your-api-key",
    "client_secret": "your-client-secret"
  }'

# 2. Get recommendations for a user
curl -X GET "https://api.playsync.com/v1/users/user123/recommendations?count=5" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

# 3. Process the recommendations in your application
# The response will contain an array of recommended users with match scores

Best Practices​

  1. Regular Updates: Keep user profiles updated to maintain recommendation quality
  2. Filter Results: Use query parameters to get more relevant recommendations
  3. Handle Errors: Implement proper error handling for cases where users don't exist
  4. Cache Tokens: Store and reuse JWT tokens until they expire (1 hour)
  5. Monitor Scores: Track match scores to understand recommendation quality

Integration Tips​

  • Call the recommendations endpoint when users are actively looking for matches
  • Store recommendation results in your application for quick access
  • Implement fallback logic for when no good matches are found
  • Consider user feedback to improve future recommendations