PC & Console S2S Integration Guide

Comprehensive guide for implementing server-to-server integration for PC and Console game attribution, enabling accurate campaign measurement and analytics across desktop and gaming platforms.

Overview

Server-to-Server Integration

Singular provides REST API enabling server-to-server reporting of PC and Console game conversion data for attribution analytics, campaign performance measurement, and user behavior tracking.

Integration Capabilities:

• Game Session Tracking: Report user sessions and activity across game launches
• Install Attribution: Attribute new game installs to marketing campaigns
• Event Analytics: Track in-game events and user interactions for funnel analysis
• Revenue Measurement: Measure in-game purchases and monetization performance
• Cross-Platform Support: Unified tracking across PC, Xbox, PlayStation, Nintendo, and Meta Quest

Prerequisites

Before implementing PC & Console S2S integration, ensure Web SDK properly configured for complete attribution workflow.

Integration Architecture

Complete PC & Console attribution requires both web-side and game-side implementation working together.

Attribution Flow:

1. User Clicks Ad: User clicks marketing campaign ad for your game
2. Landing Page Visit: User arrives at landing page with Singular Web SDK implemented
3. Click Capture: Web SDK captures click data including device fingerprint and campaign parameters
4. Game Download: User downloads and installs game from store or direct download
5. First Launch: User launches game for first time
6. Session Report: Game reports session via S2S API with device identifier
7. Attribution Matching: Singular matches game install to web click based on fingerprint or Match ID
8. Campaign Attribution: Install attributed to originating campaign for ROI measurement

Documentation Resources

Complete API reference provides endpoint specifications, parameters, and implementation examples.

Integration Concepts

Core concepts and requirements for implementing feature-complete PC & Console S2S integration with Singular.

Authentication

SDK Key Requirement

All requests to Singular's PC & Console S2S API require SDK key authentication in a parameter.

User Privacy

Privacy Compliance

Singular recommends offering end-users ability to opt-in or opt-out of tracking to preserve user privacy and comply with relevant regulations.

Implementation Options:

• Option 1: Do not send game event data to Singular when user opts out
• Option 2: Send game event data but include user consent choices via data_sharing_options parameter with "Limit Data Sharing" value

Supported Platforms

Platform Definition

Platform represents where user plays game and must be passed in p parameter on all S2S API requests.

Supported Platform Values:

• pc - Personal computer platforms
• xbox - Microsoft Xbox gaming consoles
• playstation - Sony PlayStation gaming consoles
• nintendo - Nintendo gaming consoles
• metaquest - Meta Quest VR headsets

Operating Systems and Stores

In addition to platform, specify operating/game system via os parameter and distribution store via install_source parameter.

Game Identifier

Application Identification

Game identifier associates game events with specific game and must be passed in i parameter on every request.

Identifier Requirements:

• Format: Any value supported, but Singular recommends reverse DNS notation (e.g., com.singular.game)
• Web SDK Alignment: Must match Web SDK Product ID configured on landing pages for attribution to work
• Cross-Platform Consistency: Same game identifier must be used for same game across all supported platforms

Configuration Examples:

const config = {
  apiKey: 'YOUR_SDK_KEY',
  productId: 'com.singular.game',  // Must match S2S identifier
  // ... other config
};

p=pc&i=com.singular.game

p=xbox&i=com.singular.game

p=playstation&i=com.singular.game

Device Identification

Unique Game Install Tracking

Installation/device identifier associates game events throughout multiple game sessions for same game install and must be passed in sdid parameter on every request.

Identifier Specifications:

• Format: Recommended UUID Version 4 format
• Generation: Value generated by game/server at first game launch (install)
• Persistence: Must persist throughout life of game installation
• Uniqueness: Each game installation requires unique identifier

Example: sdid=40009df0-d618-4d81-9da1-cbb3337b8dec

Match ID Attribution

Match ID enables improved attribution accuracy for web campaigns by passing unique identifier from Web SDK to game installation, providing deterministic matching alternative to fingerprint-based attribution.

How Match ID Works:

1. Web SDK Generates Match ID:Singular Web SDK creates unique Match ID when user visits landing page
2. Retrieve Match ID: Use Web SDK methods to retrieve Match ID from landing page
3. Pass to Game: Your implementation passes Match ID from web page to game during download/install process (e.g., query parameter, deep link, cookie)
4. Report with First Launch: Game includes Match ID in first session notification to Singular via match_id parameter
5. Deterministic Match: Singular uses Match ID for precise attribution matching

Web SDK Match ID Methods

Native Implementation

Singular Web SDK provides native methods for retrieving, setting, and clearing Match ID values on landing pages.

Available Methods:

Implementation Examples

// Get the Singular-generated Match ID
const matchId = window.singularSdk.getMatchID();
console.log('Match ID:', matchId);

// Store Match ID for passing to game
localStorage.setItem('singular_match_id', matchId);

// Set your own Match ID value
const customMatchId = 'your-custom-match-id-123';
window.singularSdk.setMatchID(customMatchId);

console.log('Custom Match ID set:', customMatchId);

// Clear custom Match ID and revert to default
window.singularSdk.clearMatchID();

// Get the new default Match ID
const defaultMatchId = window.singularSdk.getMatchID();
console.log('Default Match ID restored:', defaultMatchId);

// Initialize Web SDK
const config = new SingularConfig(sdkKey, sdkSecret, productId)
  .withInitFinishedCallback(() = {
    console.log('Singular SDK initialized');
  });

singularSdk.init(config);

// Handle download button click
document.getElementById('download-button').addEventListener('click', function() {
  // Get Match ID before redirecting to download
  const matchId = window.singularSdk.getMatchID();
  
  // Pass Match ID to download page via query parameter
  const downloadUrl = `https://example.com/download?match_id=${matchId}`;
  
  // Redirect to download page
  window.location.href = downloadUrl;
});

<script>
  // Match ID Management Functions for GTM

  // Get Match ID from Singular Web SDK
  function getMatchID() {
    if (window.singularSdk && window.singularSdk.getMatchID) {
      return window.singularSdk.getMatchID();
    }
    console.warn('Singular SDK not initialized');
    return null;
  }

  // Set custom Match ID
  function setMatchID(data) {
    if (!data.matchId) {
      console.warn('No matchId provided');
      return;
    }
    
    if (window.singularSdk && window.singularSdk.setMatchID) {
      window.singularSdk.setMatchID(data.matchId);
      console.log('Match ID set:', data.matchId);
    } else {
      console.warn('Singular SDK not initialized');
    }
  }

  // Clear Match ID
  function clearMatchID() {
    if (window.singularSdk && window.singularSdk.clearMatchID) {
      window.singularSdk.clearMatchID();
      console.log('Match ID cleared');
    } else {
      console.warn('Singular SDK not initialized');
    }
  }

  // Make functions available globally
  window.singularMatchID = {
    get: getMatchID,
    set: setMatchID,
    clear: clearMatchID
  };
</script>

// Get Match ID
const matchId = window.singularMatchID.get();
console.log('Match ID:', matchId);

// Set custom Match ID
window.singularMatchID.set({ matchId: 'custom-id-123' });

// Clear Match ID
window.singularMatchID.clear();

<script>
  // Trigger on button click
  document.addEventListener('DOMContentLoaded', function() {
    const downloadButton = document.getElementById('download-button');
    
    if (downloadButton) {
      downloadButton.addEventListener('click', function() {
        // Get Match ID via GTM function
        const matchId = window.singularMatchID.get();
        
        if (matchId) {
          // Push to dataLayer for GTM
          window.dataLayer = window.dataLayer || [];
          window.dataLayer.push({
            'event': 'download_click',
            'singular_match_id': matchId
          });
          
          // Redirect with Match ID
          const downloadUrl = `https://example.com/download?match_id=${matchId}`;
          window.location.href = downloadUrl;
        }
      });
    }
  });
</script>

Passing Match ID to Game

Implementation Strategies

After retrieving Match ID from Web SDK, implement mechanism to pass value from landing page to game installation.

Common Approaches:

https://example.com/download?match_id=abc123

document.cookie = `match_id=${matchId}; path=/; max-age=86400`;

localStorage.setItem('singular_match_id', matchId);

mygame://install?match_id=abc123

S2S API Implementation

Reporting Match ID

Once game retrieves Match ID from web implementation, include in first session notification to Singular for attribution matching.

Session Request with Match ID:

import requests

def report_first_session_with_match_id(sdk_key, game_id, device_id, platform, match_id):
    """
    Report first game session with Match ID for attribution
    """
    session_url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': 'windows',
        'install_source': 'steam',
        'ip': get_user_ip(),
        'match_id': match_id  # Include Match ID for attribution
    }
    
    response = requests.get(session_url, params=params)
    return response.json()

# Example: First launch with Match ID
report_first_session_with_match_id(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    match_id='abc123def456'  # Retrieved from landing page
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235" \
  --data-urlencode "match_id=abc123def456"

async function reportFirstSessionWithMatchId(config) {
    const sessionUrl = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': await getUserIP(),
        'match_id': config.matchId  // Include Match ID
    });
    
    const response = await fetch(`${sessionUrl}?${params.toString()}`);
    return await response.json();
}

// Example: First launch with Match ID
reportFirstSessionWithMatchId({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    matchId: 'abc123def456'  # Retrieved from landing page
});

Match ID Best Practices

Implementation Checklist

For complete attribution methodology details and troubleshooting, see PC and Console Game Attribution FAQ.

Game Session Tracking

Reporting game sessions to Singular is required in PC & Console integration, enabling install attribution, re-engagement tracking, and user retention analytics.

Session Notification Endpoint

Implementation Requirement

Call Session Notification Endpoint each time game launches to notify Singular about game session.

Session Processing

Attribution Workflow

Session notifications enable Singular to perform multiple attribution and analytics functions based on session context.

Processing Logic:

• First Session (Install): If first game session after unique install, Singular recognizes new install and triggers install attribution process
• Re-engagement Session: If session qualifies as re-engagement (coming soon), Singular triggers re-engagement attribution process (see Re-engagement FAQ)
• Regular Session: Otherwise, marked as game session for user activity and retention tracking

Implementation Best Practices

Asynchronous Data Collection

When collecting data to report game session, wait for asynchronous functions to return and handle various functionality before sending session notification.

Session Request Example

Sample Implementation

import requests

def report_game_session(sdk_key, game_id, device_id, platform, os_version, store):
    """
    Report game session to Singular
    """
    session_url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'os': os_version,
        'install_source': store,
        'ip': get_user_ip()
    }
    
    try:
        response = requests.get(session_url, params=params, timeout=10)
        
        if response.status_code == 200:
            data = response.json()
            if data.get('status') == 'ok':
                print("Session reported successfully")
                return True
            else:
                print(f"Session error: {data.get('reason')}")
                return False
        else:
            print(f"HTTP error: {response.status_code}")
            return False
            
    except Exception as e:
        print(f"Exception reporting session: {e}")
        return False

# Example usage
report_game_session(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    os_version='windows',
    store='steam'
)

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

async function reportGameSession(config) {
    const sessionUrl = 'https://s2s.singular.net/api/v1/launch';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'os': config.osVersion,
        'install_source': config.store,
        'ip': await getUserIP()
    });
    
    try {
        const response = await fetch(`${sessionUrl}?${params.toString()}`);
        const data = await response.json();
        
        if (data.status === 'ok') {
            console.log('Session reported successfully');
            return true;
        } else {
            console.error('Session error:', data.reason);
            return false;
        }
    } catch (error) {
        console.error('Exception reporting session:', error);
        return false;
    }
}

// Example usage
reportGameSession({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam'
});

In-Game Event Tracking

Track in-game events and user interactions to analyze marketing campaign performance, optimize user funnels, and measure engagement across player journey.

Event Planning

Event Definition

Before implementing S2S integration, define events your organization wants to track for campaign analysis and user behavior measurement.

Event Planning Guide:Defining In-Game Events

Event Notification Endpoint

Event Reporting

Call Event Notification Endpoint when event occurs in game to notify Singular for attribution analysis and campaign optimization.

Event name included in API call determines how event identified in Singular reports, exports, and postbacks.

Event Naming Best Practices

Standard Events

Singular recommends using standard event and attribute naming convention for streamlined partner integration and analytics compatibility.

Revenue Event Tracking

Revenue Measurement

Track revenue from in-game purchases to analyze campaign performance and ROI, with data available in reports, log exports, and postbacks.

Revenue Event Implementation: Use Event Notification Endpoint with additional revenue parameters to designate revenue events.

Required Revenue Parameters:

• is_revenue_event=true - Marks event as revenue event (optional if event name is __iap__ or amount larger than zero)
• amt=1.99 - Revenue amount
• cur=USD - ISO 4217 currency code

Event Request Examples

Sample Implementations

import requests

def report_game_event(sdk_key, game_id, device_id, platform, event_name, event_attributes=None):
    """
    Report in-game event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': event_name,
        'ip': get_user_ip()
    }
    
    if event_attributes:
        import json
        params['e'] = json.dumps(event_attributes)
    
    response = requests.get(event_url, params=params)
    return response.json()

# Example: Level complete event
report_game_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    event_name='sng_level_achieved',
    event_attributes={
        'level': '5',
        'score': '1250'
    }
)

def report_revenue_event(sdk_key, game_id, device_id, platform, amount, currency):
    """
    Report revenue event to Singular
    """
    event_url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': sdk_key,
        'i': game_id,
        'sdid': device_id,
        'p': platform,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': amount,
        'cur': currency,
        'ip': get_user_ip()
    }
    
    response = requests.get(event_url, params=params)
    return response.json()

# Example: $9.99 purchase
report_revenue_event(
    sdk_key='your_sdk_key_here',
    game_id='com.singular.game',
    device_id='40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform='pc',
    amount=9.99,
    currency='USD'
)

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"level":"5","score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key_here" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=40009df0-d618-4d81-9da1-cbb3337b8dec" \
  --data-urlencode "p=pc" \
  --data-urlencode "n=__iap__" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=9.99" \
  --data-urlencode "cur=USD" \
  --data-urlencode "ip=172.58.29.235"

async function reportGameEvent(config) {
    const eventUrl = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'n': config.eventName,
        'ip': await getUserIP()
    });
    
    if (config.attributes) {
        params.append('e', JSON.stringify(config.attributes));
    }
    
    const response = await fetch(`${eventUrl}?${params.toString()}`);
    return await response.json();
}

// Example: Level complete
reportGameEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    eventName: 'sng_level_achieved',
    attributes: {
        level: '5',
        score: '1250'
    }
});

async function reportRevenueEvent(config) {
    const eventUrl = 'https://s2s.singular.net/api/v1/evt';
    
    const params = new URLSearchParams({
        'a': config.sdkKey,
        'i': config.gameId,
        'sdid': config.deviceId,
        'p': config.platform,
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config.amount,
        'cur': config.currency,
        'ip': await getUserIP()
    });
    
    const response = await fetch(`${eventUrl}?${params.toString()}`);
    return await response.json();
}

// Example: $9.99 purchase
reportRevenueEvent({
    sdkKey: 'your_sdk_key_here',
    gameId: 'com.singular.game',
    deviceId: '40009df0-d618-4d81-9da1-cbb3337b8dec',
    platform: 'pc',
    amount: 9.99,
    currency: 'USD'
});

Next Steps

Complete your PC & Console S2S integration with additional resources and support.

Additional Resources

Documentation & Support

• Web SDK:Web SDK Overview & Getting Started
• API Reference:PC & Console S2S Endpoint Reference
• Attribution Guide:PC and Console Game Attribution FAQ
• Event Planning:Defining In-Game Events
• Standard Events:Singular Standard Events Reference
• Response Codes:S2S Response Codes & Error Handling

Support Channels

Getting Help

Contact Singular team for implementation assistance and technical support.

• Solution Engineer: Consult with Singular Solution Engineer for advanced features and integration planning
• Customer Success Manager: Contact CSM for enterprise feature enablement and account configuration
• Support Team: Submit support tickets for technical issues and troubleshooting assistance