PC & Console Game Integration Guide

Comprehensive guide for implementing PC and Console game attribution with Singular, enabling accurate campaign measurement and analytics across desktop and gaming platforms.

Overview

Integration Options

Singular provides two approaches for PC and Console game attribution. Select the method that best fits your implementation requirements and attribution needs.

Attribution Flow Comparison

PC/Console Singular Links Flow:

1. User Clicks Singular Link: User clicks Singular tracking link in marketing campaign
2. Redirect to Landing Page: User redirected to landing page or store (no Web SDK required)
3. Download & Install: User downloads and installs game
4. First Launch: User launches game for first time
5. S2S Report: Game reports session via S2S API
6. Probabilistic Attribution: Singular matches game install to Singular Link click based on IP address

Web SDK + Match ID Flow:

1. User Clicks Campaign Link: User clicks marketing campaign ad or link
2. Landing Page with Web SDK: User arrives at landing page with Singular Web SDK implemented
3. Click Capture: Web SDK captures click data and generates Match ID
4. User Authentication (Optional): If user logs in, Match ID can be passed to game for deterministic attribution
5. Download & Install: User downloads and installs game
6. First Launch: User launches game and optionally retrieves Match ID
7. S2S Report with Match ID: Game reports session via S2S API with or without Match ID
8. Attribution Matching: Singular performs deterministic matching (if Match ID provided) or probabilistic matching (IP-based)

Server-to-Server Integration

Regardless of attribution method chosen, implementing the S2S API integration is required for all PC and Console game attribution.

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 integration, ensure the following requirements are met.

Documentation Resources

Complete API reference and implementation guides for PC & Console integration.

Method 1: PC/Console Singular Links (Recommended)

Simplified integration approach using Singular tracking links for probabilistic attribution without requiring Web SDK implementation on landing pages.

Overview

How It Works

PC/Console Singular Links enable attribution by capturing click data directly in the tracking link, eliminating the need for Web SDK implementation on landing pages.

Key Benefits:

• No Web SDK Required: Redirect users to any landing page including third-party stores (Steam, Epic, etc.)
• Simplified Integration: Only requires S2S API implementation on game side
• Fast Deployment: Create and launch campaigns quickly without landing page modifications
• Flexible Destinations: Support for single redirect to any destination URL

Attribution Method:

• Probabilistic (IP-based): Singular matches game install to Singular Link click based on IP address and device characteristics

Implementation Steps

Step 1: Prerequisites

Ensure the following requirements are met before creating PC/Console Singular Links.

Step 2: Create PC/Console Singular Link

Create PC/Console Singular Links in the Singular dashboard to track campaign clicks and enable attribution.

Configuration Steps:

1. Navigate to Manage Links: In Singular dashboard, go to Attribution → Manage Links
2. Select App: Choose an App that has PC/Console app sites configured
3. Create New Link: Click Create New Link button
4. Select Platform Type: Under Platform Tracking Type field, select "PC/Console"
5. Configure Target: Select specific PC/Console app site or choose "Track all app sites under this app" option
6. Set Destination URL: Configure redirect URL (landing page, store page, etc.)
7. Configure Attribution Settings: Set attribution windows and tracking parameters as needed
8. Generate Link: Save and generate Singular tracking link

Step 3: Implement S2S Integration

Implement Server-to-Server API integration to report game sessions and events. See the Integration Concepts section below for complete S2S implementation details.

Required Implementation:

• Session Notification: Report game launches using Session Notification Endpoint
• Event Tracking: Report in-game events and revenue using Event Notification Endpoint
• Device Identification: Generate and persist unique device identifier (SDID)

Step 4: Launch Campaigns

Use generated PC/Console Singular Links in marketing campaigns to enable attribution tracking.

Campaign Setup:

• Copy Tracking Link: Copy generated Singular Link from Manage Links
• Configure Campaign: Use Singular Link as campaign destination URL
• Launch Campaign: Activate campaign with Singular Link
• Monitor Attribution: View attribution data in Singular reports as users click links and launch game

Attribution Matching

How Attribution Works

When using PC/Console Singular Links, Singular performs probabilistic attribution matching based on IP address and timing.

Attribution Process:

1. User Clicks Singular Link: Click data captured by Singular including IP address and timestamp
2. User Downloads Game: User proceeds to download and install game
3. Game Launch: User launches game for first time
4. S2S Report: Game reports session to Singular via S2S API including user IP address
5. Probabilistic Matching: Singular matches game install to Singular Link click based on IP address within attribution window
6. Attribution Complete: Install attributed to campaign source

Method 2: Web SDK + Match ID (Advanced)

Advanced integration approach using Singular Web SDK on landing pages with optional Match ID for deterministic attribution when users authenticate.

Overview

When to Use This Method

Implement Web SDK + Match ID approach when your use case requires enhanced attribution capabilities beyond basic probabilistic matching.

Use Cases:

• Web Attribution: You need Singular Web Attribution features and web analytics
• Deterministic Attribution: Users authenticate on landing pages and you want highest attribution accuracy
• Cross-Device Tracking: Users may download game on different device than landing page visit
• Advanced Analytics: You need detailed web engagement metrics before game install

Attribution Methods:

• Probabilistic (IP-based): Automatic matching based on IP address (same as PC/Console Singular Links)
• Deterministic (Match ID): Precise matching using unique identifier passed from landing page to game when user authenticates

Implementation Steps

Step 1: Implement Web SDK

Implement Singular Web SDK on marketing landing pages to capture click data and enable attribution.

Web SDK Implementation:

• Follow Web SDK Guide: Web SDK Overview & Getting Started
• Product ID Configuration: Web SDK Product ID must match game identifier ( i parameter) used in S2S integration
• Landing Page Deployment: Deploy Web SDK to all marketing landing pages

Step 2: Implement S2S Integration

Implement Server-to-Server API integration to report game sessions and events. See the Integration Concepts section below for complete S2S implementation details.

Required Implementation:

• Session Notification: Report game launches using Session Notification Endpoint
• Event Tracking: Report in-game events and revenue using Event Notification Endpoint
• Device Identification: Generate and persist unique device identifier (SDID)

Step 3: Implement Match ID (Optional)

For deterministic attribution, implement Match ID to pass unique identifier from landing page to game when users authenticate.

Match ID Implementation:

• Retrieve Match ID: Use Web SDK getMatchID() method after user authentication
• Pass to Game: Implement mechanism to pass Match ID from web to game (query parameter, API, etc.)
• Include in First Session: Report Match ID in first game session via match_id parameter

See the Match ID Implementation section below for detailed Match ID integration steps.

Attribution Matching

How Attribution Works

When using Web SDK, Singular performs attribution matching using either probabilistic or deterministic methods depending on whether Match ID is provided.

Probabilistic Attribution (No Match ID):

1. User Clicks Campaign: User clicks marketing campaign link
2. Landing Page Visit: Web SDK captures click data including IP address
3. User Downloads Game: User downloads and installs game
4. Game Launch: User launches game for first time
5. S2S Report: Game reports session to Singular via S2S API
6. IP Matching: Singular matches game install to web click based on IP address

Deterministic Attribution (With Match ID):

1. User Clicks Campaign: User clicks marketing campaign link
2. Landing Page Visit: Web SDK generates unique Match ID
3. User Authenticates: User logs in on landing page
4. Match ID Retrieved: Implementation retrieves Match ID from Web SDK
5. Match ID Passed to Game: Match ID passed to game via query parameter, API, or other mechanism
6. User Downloads Game: User downloads and installs game
7. Game Launch with Match ID: User launches game, retrieves stored Match ID
8. S2S Report with Match ID: Game reports first session including match_id parameter
9. Deterministic Matching: Singular matches game install to web click using Match ID for precise attribution

Integration Concepts

Core concepts and requirements for implementing PC & Console S2S integration with Singular. These concepts apply to both attribution methods.

Authentication

All requests to Singular's PC & Console S2S API require SDK key authentication in the a parameter. For the shared authentication mechanics (where to find your SDK Key and how it is passed), see Authentication in S2S Fundamentals .

User Privacy

Singular recommends offering end-users the ability to opt in or opt out of tracking. For the shared privacy parameters, including data_sharing_options and Limit Data Sharing, see Privacy parameters in S2S Fundamentals .

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 )
• Cross-Platform Consistency: Same game identifier must be used for same game across all supported platforms
• Web SDK Alignment (Method 2 only): If using Web SDK + Match ID method, game identifier must match Web SDK Product ID configured on landing pages for attribution to work

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 Implementation

Match ID enables deterministic attribution for web campaigns by passing unique identifier from Web SDK to game installation. This feature is only available when using Web SDK + Match ID attribution method.

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 after user authentication
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;
});

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 integration with additional resources and support.

Additional Resources

Documentation & Support

• API Reference: PC & Console S2S Endpoint Reference
• Attribution FAQ: PC and Console Game Attribution FAQ
• Web SDK (Optional): Web SDK Overview & Getting Started
• 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