文档

PC与主机端API端点参考

PC与主机端服务器间通信的完整API参考文档，提供会话追踪与事件报告的详细参数规范及实现示例。

企业级功能：PC与主机游戏归因属于企业级功能。了解更多信息，请阅读 PC与主机游戏归因常见问题解答或联系您的客户成功经理。

集成指南：完整实现说明及最佳实践请参阅《PC与主机S2S集成指南》。

会话通知接口

向Singular报告游戏启动和会话数据，用于安装归因、重新激活追踪及用户留存分析。

端点规范

方法	URL
`GET`	`https://s2s.singular.net/api/v1/launch`

用途

使用会话通知端点近实时报告所有游戏启动（首次及重复会话）。Singular接收到的首次游戏启动（通过安装识别）将触发归因流程。

归因工作流：

首次会话：触发安装归因匹配网页广告点击
后续会话：追踪用户行为、留存率及重新参与度分析
实时报告：尽可能在游戏启动后立即发送会话通知

会话参数

必填参数

参数	描述	限制条件	示例
`a`	用于API身份验证的唯一SDK密钥。位置：仪表板 → 开发者工具 → SDK集成 → SDK密钥重要提示：请使用 SDK 密钥，而非报告 API 密钥	必填字符串	`your_org_name_sh868sdjv`
`p`	用户游戏所在平台。支持值： `pc` `xbox` `playstation` `nintendo` `metaquest`	必填字符串区分大小写	`pc`
`i`	游戏标识符，需为您的游戏提供唯一标识。关键：必须与Web SDK产品ID完全匹配才能正常归因。同一游戏在所有平台应使用相同值。	必填建议使用反向DNS格式区分大小写	`com.singular.game`
`sdid`	唯一设备ID用于标识特定游戏安装实例及用户活动。生成机制：由游戏/服务器在首次启动时创建，在游戏安装周期内持续有效。	必填推荐使用UUID版本4格式	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	操作系统或游戏系统。支持自定义值，但建议按平台使用以下值： PC：windows, linux, macos, steamos Xbox：xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation：playstation_3, playstation_4, playstation_5 任天堂：nintendo_switch Meta Quest：metaquest, metaquest_2, metaquest_pro	必需支持自定义值	`windows`
`install_source`	游戏商店或分发方式。推荐值： `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` 支持自定义值	必填支持自定义值	`steam`
`ip`	游戏启动时设备的IP地址。替代方案：使用`use_ip=true` 从HTTP请求头提取IP地址，而非显式传递。	必填 IPv4 或 IPv6 格式若使用`use_ip=true`则无需指定	`172.58.29.235`

可选参数

参数	描述	限制	示例
`install_ref`	JSON URL编码的Google安装来源信息。为通过Google Play游戏商店分发的原生PC游戏提供最精确的归因数据。要求：需实现 Play Games PCSDK 以传递仅需在首次游戏启动时发送具体实现细节请参阅 Google Play原生PC安装来源文档	可选字符串仅限首次启动	`%7B%22install_time_epoch_seconds%22%3A%221568939453%22` `%2C%22install_referrer%22%3A%22utm_source%3Dgoogle-play%26utm_medium%3Dorganic%22%7D`
`match_id`	用于确定性归因匹配的标识符，将网页点击与游戏安装关联。要求：仅限首次游戏启动时发送必须与Web SDK实现中的值匹配若涉及个人身份信息，必须使用SHA-256算法进行哈希处理具体实现细节请参阅匹配ID归因文档。	可选字符串仅首次启动时	`matchid_12345`
`ve`	操作系统版本。	可选字符串	`22H2`
`av`	应用程序版本或游戏构建标识符。	可选字符串	`1.1.5.581823a`
`use_ip`	从HTTP请求头提取IP地址，无需显式提供 `ip` 参数。若设置为`true` ，则无需提供`ip`参数。	可选布尔值默认值：false	`true`
`ua`	设备的用户代理字符串。	可选字符串	`Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36`
`global_properties`	为用户保存的键值对，并在所有后续请求中保持有效。设置键值对后，后续请求将使用该值。发送新值将覆盖先前设置的值。格式：URL编码的JSON对象	可选最多5个属性每项最多200个字符 URL编码的JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	用户同意共享信息以符合隐私合规要求。若已设置，必须在后续每次请求中保持并传递值： `"limit_data_sharing":false` - 用户选择加入（同意） `"limit_data_sharing":true` - 用户选择退出（拒绝）参见用户隐私获取实施指南。	可选 URL编码的JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`install`	安装标记，用于标识游戏安装后的首次会话。用于重新安装追踪功能。	可选布尔值	`true`
`utime`	游戏启动的时间戳（UNIX时间，以秒为单位）。	可选整数（UNIX时间戳）	`1483228800`
`umilisec`	游戏启动的UNIX时间戳（毫秒）。	可选整数（UNIX时间戳毫秒）	`1483228800000`
`custom_user_id`	来自您系统的自定义用户标识符。	可选字符串	`123456789abcd`

请求示例

示例实现

基本会话请求

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "ip=172.58.29.235"

首次启动时使用匹配ID

curl -G "https://s2s.singular.net/api/v1/launch" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --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" \
  --data-urlencode "install=true"

基本会话请求

import requests

def report_session(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_session({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'ip_address': '172.58.29.235'
})

首次启动时使用匹配ID

def report_first_launch(config):
    url = "https://s2s.singular.net/api/v1/launch"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'ip': config['ip_address'],
        'match_id': config['match_id'],
        'install': 'true'
    }
    
    response = requests.get(url, params=params)
    return response.json()

基本会话请求

async function reportSession(config) {
    const url = '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': config.ipAddress
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

// Example usage
reportSession({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    ipAddress: '172.58.29.235'
});

首次启动时使用匹配ID

async function reportFirstLaunch(config) {
    const url = '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': config.ipAddress,
        'match_id': config.matchId,
        'install': 'true'
    });
    
    const response = await fetch(`${url}?${params.toString()}`);
    return await response.json();
}

事件通知端点

向Singular报告游戏内事件，用于分析、活动优化以及合作伙伴转发。

端点规范

方法	URL
`GET`	`https://s2s.singular.net/api/v1/evt`

用途

使用事件通知端点近乎实时地报告所有所需游戏内事件。事件数据用于分析、报告、合作伙伴优化以及活动效果评估。

事件最佳实践：

标准事件：使用统一标准事件名称实现自动合作伙伴映射
实时报告：尽可能在事件发生后立即发送 实时报告：尽可能在事件发生后立即发送
收入事件：包含收入参数以追踪购买行为并进行投资回报率分析

事件参数

必填参数

参数	描述	限制条件	示例
`a`	用于API身份验证的唯一SDK密钥。位置：仪表盘 → 开发者工具 → SDK集成 → SDK密钥	必填字符串	`your_org_name_sh868sdjv`
`p`	用户游戏所处平台。支持值：pc, xbox, playstation, nintendo, metaquest	必填字符串区分大小写	`pc`
`i`	游戏标识符，需为您的游戏唯一标识。必须与会话通知及Web SDK产品ID中使用的值一致。	必填建议使用反向DNS格式区分大小写	`com.singular.game`
`sdid`	用于标识唯一游戏安装的设备ID（Singular形式）。必须与会话通知中使用的SDID匹配。	必填 UUID格式	`49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	事件名称用于标识游戏内操作或里程碑。推荐：使用 Singular标准事件名称以实现自动合作伙伴集成。	必填字符串最多32个ASCII字符	`sng_achievement_unlocked`
`os`	操作系统或游戏系统。必须与会话通知中使用的值匹配。	必填支持自定义值	`windows`
`install_source`	游戏商店或分发方式。必须与会话通知中使用的值匹配。	必填支持自定义值	`steam`
`ip`	事件发生时设备的IP地址。	必填 IPv4 或 IPv6 格式若为`use_ip=true`则非必需	`172.58.29.235`

可选参数

参数	描述	限制	示例
`e`	自定义事件属性，提供关于事件的丰富信息。建议：为确保合作伙伴兼容性，请使用Singular标准属性名称。	可选 URL编码的JSON 每个属性最多500个ASCII字符	`%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	标记事件为收入事件。若事件名称为`__iap__` 或提供非零`amt` 则可省略。	收入事件必填布尔值	`true`
`amt`	收入事件的货币金额。需与`cur` 参数配合使用。	收入事件必填十进制数	`2.51`
`cur`	收入事件的ISO-4217三字母货币代码。需与`amt` 参数配合使用。参考： ISO-4217 货币代码	收入事件必填项 ISO-4217代码	`EUR`
`ve`	操作系统版本。	可选字符串	`22H2`
`av`	应用程序版本或游戏构建标识符。	可选字符串	`1.1.5.581823a`
`use_ip`	从 HTTP 请求头中提取 IP 地址。	可选布尔默认值：false	`true`
`ua`	设备的用户代理字符串。	可选字符串	`Mozilla/5.0 (Windows NT 10.0; Win64; x64)`
`global_properties`	为用户保存的键值对。若已设置，必须在后续所有请求中保持有效。	可选最多5个属性每个属性最多200个字符 URL编码的JSON	`%7B%22key1%22%3A%22value1%22%7D`
`data_sharing_options`	用户同意共享信息。若已设置，必须在后续所有请求中保持有效。	可选 URL编码的JSON	`%7B%22limit_data_sharing%22%3Atrue%7D`
`utime`	事件的时间戳（UNIX时间，以秒为单位）。	可选整数（UNIX 时间戳）	`1483228800`
`umilisec`	事件的UNIX时间戳（毫秒）。	可选整数（UNIX时间戳毫秒）	`1483228800000`
`custom_user_id`	来自您系统的自定义用户标识符。	可选字符串	`123456789abcd`

请求示例

示例实现

标准事件

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --data-urlencode "n=sng_level_achieved" \
  --data-urlencode 'e={"sng_attr_level":"5","sng_attr_score":"1250"}' \
  --data-urlencode "ip=172.58.29.235"

收入事件

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=your_sdk_key" \
  --data-urlencode "i=com.singular.game" \
  --data-urlencode "sdid=49c2d3a6-326e-4ec5-a16b-0a47e34ed953" \
  --data-urlencode "p=pc" \
  --data-urlencode "os=windows" \
  --data-urlencode "install_source=steam" \
  --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"

标准事件

import requests
import json

def report_event(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': config['event_name'],
        'ip': config['ip_address']
    }
    
    if 'attributes' in config:
        params['e'] = json.dumps(config['attributes'])
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_event({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'event_name': 'sng_level_achieved',
    'attributes': {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    'ip_address': '172.58.29.235'
})

收入事件

def report_revenue(config):
    url = "https://s2s.singular.net/api/v1/evt"
    
    params = {
        'a': config['sdk_key'],
        'i': config['game_id'],
        'sdid': config['device_id'],
        'p': config['platform'],
        'os': config['os_version'],
        'install_source': config['store'],
        'n': '__iap__',
        'is_revenue_event': 'true',
        'amt': config['amount'],
        'cur': config['currency'],
        'ip': config['ip_address']
    }
    
    response = requests.get(url, params=params)
    return response.json()

# Example usage
report_revenue({
    'sdk_key': 'your_sdk_key',
    'game_id': 'com.singular.game',
    'device_id': '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    'platform': 'pc',
    'os_version': 'windows',
    'store': 'steam',
    'amount': 9.99,
    'currency': 'USD',
    'ip_address': '172.58.29.235'
})

标准事件

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

// Example usage
reportEvent({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    eventName: 'sng_level_achieved',
    attributes: {
        'sng_attr_level': '5',
        'sng_attr_score': '1250'
    },
    ipAddress: '172.58.29.235'
});

收益事件

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

// Example usage
reportRevenue({
    sdkKey: 'your_sdk_key',
    gameId: 'com.singular.game',
    deviceId: '49c2d3a6-326e-4ec5-a16b-0a47e34ed953',
    platform: 'pc',
    osVersion: 'windows',
    store: 'steam',
    amount: 9.99,
    currency: 'USD',
    ipAddress: '172.58.29.235'
});

响应处理

两个端点均返回一致的JSON响应，需验证 status 字段以判断成功或错误状态。

响应格式

重要提示：所有响应均返回HTTP 200状态码。必须始终验证响应正文中的status 字段以判断成功 (ok) 或失败(error)。

完整响应码文档及错误处理策略详见《S2S响应码与错误处理指南》。

附加资源

集成指南：PC与主机S2S集成指南
Web SDK：Web SDK 概述与入门指南
归因常见问题：PC与主机游戏归因FAQ
标准事件：Singular标准事件参考

PC与主机平台 - API 端点参考

PC与主机端API端点参考

会话通知接口

端点规范

用途

会话参数

必填参数

可选参数

请求示例

示例实现

基本会话请求

首次启动时使用匹配ID

基本会话请求

首次启动时使用匹配ID

基本会话请求

首次启动时使用匹配ID

事件通知端点

端点规范

用途

事件参数

必填参数

可选参数

请求示例

示例实现

标准事件

收入事件

标准事件

收入事件

标准事件

收益事件

响应处理

响应格式

附加资源