PC 与主机 API 端点参考

面向 PC 和主机的 server-to-server 端点完整 API 参考，提供用于会话追踪和事件上报的详细参数说明及实现示例。

相关参考： PC 与主机使用与套件其余部分相同的 S2S 端点。有关移动端和 Web 端的对应内容，请参阅 SESSION 端点参考和 EVENT 端点参考。本参考涵盖 PC 与主机的会话和事件端点。

企业版功能： PC 和主机游戏归因属于企业版功能。如需了解更多，请阅读 PC 和主机游戏归因常见问题解答或联系您的 Customer Success Manager。

集成指南： 有关完整的实现说明和最佳实践，请参阅 PC 与主机 S2S 集成指南。

会话通知端点

向 Singular 上报游戏启动和会话，用于安装归因、再互动追踪和用户留存分析。

端点规范

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

参数作为 application/x-www-form-urlencoded 请求体发送。请包含以下必需的请求头：

Content-Type: application/x-www-form-urlencoded

用途

使用会话通知端点近乎实时地上报所有游戏启动（首次会话和重复会话）。Singular 收到由 Singular Device ID 标识的安装的首次游戏启动时，会触发归因流程。

归因工作流程：

首次会话： 触发安装归因，与网页广告活动的点击进行匹配
后续会话： 用于追踪用户活动、留存和再互动分析
实时上报： 尽可能在游戏实际启动的同时发送会话通知

会话参数

必需参数

参数	详情
`a`	类型： String 必需。用于 API 身份验证的 Singular SDK 密钥。获取途径： Singular UI → 主菜单 → Developer Tools 。重要提示：请勿使用 Reporting API 密钥。请求将被拒绝。示例： `sdkKey_afdadsf7asf56`
`p`	类型： String 必需。区分大小写。用户玩游戏所在的平台。支持的值：示例： `PC` `PC` `Xbox` `Playstation` `Nintendo` `MetaQuest`
`i`	类型： String 必需。区分大小写。建议使用反向 DNS 表示法。为您的游戏指定的唯一游戏标识符。关键：必须与 Web SDK Product ID 完全一致，归因才能正常工作。同一游戏在所有平台上使用相同的值。示例： `com.singular.game`
`sdid`	类型： UUIDv4 必需。建议使用 UUID 第 4 版格式。用于标识唯一游戏安装和用户活动的 Singular Device ID。生成方式：由游戏/服务器在首次启动时创建，在整个游戏安装生命周期内持续存在。示例： `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`os`	类型： String 必需。支持自定义值。操作系统或游戏系统。各平台推荐值： PC： windows, linux, macos, steamos Xbox： xbox_one, xbox_360, xbox_series_s, xbox_series_x PlayStation： playstation_3, playstation_4, playstation_5 Nintendo： nintendo_switch Meta Quest： metaquest, metaquest_2, metaquest_pro 示例： `windows`
`install_source`	类型： String 必需。支持自定义值。游戏商店或分发方式。推荐值：支持自定义值。示例： `steam` `steam` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed`
`ip`	类型： String 必需。 IPv4 或 IPv6 格式。如果设置了 `use_ip=true` 则不需要。游戏启动时设备的 IP 地址。替代方式：使用 `use_ip=true` 从 HTTP 请求头中提取 IP，而无需显式传递。示例： `172.58.29.235`

可选参数

支持以下可选参数。

参数	详情
`install_ref`	类型： String 可选。仅限首次启动。经过 JSON URL 编码的 Google Install Referrer 信息。为通过 Google Play Games 商店分发的原生 PC 游戏提供最准确的归因。要求：需要实现 Play Games PC SDK 以传递该信息只能在首次游戏启动时发送有关实现细节，请参阅 Google Play for Native PC Install Referrer 文档。示例： `%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`	类型： String 可选。仅限首次启动。用于将网页点击与游戏安装进行确定性归因匹配的标识符。要求：只能在首次游戏启动时发送必须与 Web SDK 实现中的值匹配如果是 PII，必须使用 SHA-256 进行哈希处理有关实现细节，请参阅 Match ID 归因。示例： `matchid_12345`
`av`	类型： String 可选。应用版本或游戏构建标识符。示例： `1.1.5.581823a`
`global_properties`	类型： JSON 可选。经过 URL 编码的 JSON。最多 5 个属性，每个最多 200 个字符。为用户保存的键值对，并在所有后续请求中持续保留。不发送先前设置的值将取消该值。示例： `%7B%22key1%22%3A%22value1%22%7D`
`install`	类型： Boolean 可选。标识游戏安装后首次会话的安装标志。用于重新安装追踪功能所必需。示例： `true`
`utime`	类型： Integer 可选。 UNIX 时间戳（秒）。以 UNIX 时间表示的游戏启动时间戳。示例： `1483228800`
`umilisec`	类型： Integer 可选。 UNIX 时间戳（毫秒）。以 UNIX 时间表示的游戏启动时间戳。示例： `1483228800000`
`ve`	类型： String 可选。示例： `9.2` 会话发生时设备的操作系统版本。
`ua`	类型： String 可选。经过 URL 编码的 User Agent 字符串。原始： `Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...` 示例： `Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...`
`use_ip`	类型： Boolean 可选。指示 Singular 从 HTTP 请求中提取 IP 地址，而不是从 `ip` 参数中提取。限制：阻止 Singular 进行基于 IP 的地理定位。通过 `country` 参数提供两字母国家/地区代码。与 `ip` 参数互斥——请勿同时使用两者。必须提供 `ip` 或 `use_ip` 之一，以避免数据被拒绝。示例： `true`
`data_sharing_options`	类型： JSON 可选。经过 JSON URL 编码的最终用户数据共享同意。必须持久保存，并在所有后续的 SESSION 和 EVENT 请求中传递。用户已同意（选择加入）：用户已拒绝（选择退出）：示例： `%7B%22limit_data_sharing%22%3Atrue%7D` `{"limit_data_sharing":false}` `{"limit_data_sharing":true}`
`custom_user_id`	类型： String 可选。用于跨设备追踪的您的内部用户 ID。禁止 PII：请勿传递个人身份信息。请使用经过哈希处理或以其他方式匿名化的内部标识符，而不是原始的电子邮件地址、电话号码或姓名。示例： `123456789abcd`

请求示例

示例实现

基本会话请求

curl -X POST "https://s2s.singular.net/api/v1/launch" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --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"

使用 Match ID 的首次启动

curl -X POST "https://s2s.singular.net/api/v1/launch" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
    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'
})

使用 Match 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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
    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, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: 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'
});

使用 Match 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, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: params.toString()
    });
    return await response.json();
}

事件通知端点

合作伙伴 Conversion API 支持： 要通过 Singular 的 Conversion API 集成将这些事件转发给广告网络合作伙伴，请包含标准的可选事件属性（经过哈希处理的第一方数据，例如 eventId 和 ehash ）。请参阅面向 Conversion API 集成的标准事件属性。

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

自 2026 年 7 月 15 日起必须使用 V2。 在 2026 年 7 月 15 日当天或之后创建的账户必须使用 Event Endpoint V2（基于 SDID）；新账户无法使用 V1。已通过 V1 完成集成的现有客户不受影响。如需迁移到 V2，请联系您的 Singular Customer Success Manager。

端点规范

方法	URL
`POST`	`https://s2s.singular.net/api/v2/evt`

参数作为 application/x-www-form-urlencoded 请求体发送。请包含以下必需的请求头：

Content-Type: application/x-www-form-urlencoded

用途

使用事件通知端点近乎实时地上报所有所需的游戏内事件。事件数据用于分析、报告、合作伙伴优化和广告活动效果衡量。

事件最佳实践：

标准事件： 使用 Singular 标准事件名称以实现自动的合作伙伴映射
实时上报： 尽可能在事件实际发生的同时发送事件
收入事件： 包含收入参数以进行购买追踪和 ROI 分析

事件参数

必需参数

参数	详情
`a`	类型： String 必需。用于 API 身份验证的 Singular SDK 密钥。获取途径： Singular UI → 主菜单 → Developer Tools 。重要提示：请勿使用 Reporting API 密钥。请求将被拒绝。示例： `sdkKey_afdadsf7asf56`
`p`	类型： String 必需。区分大小写。用户玩游戏所在的平台。支持的值： PC, Xbox, Playstation, Nintendo, MetaQuest 示例： `PC`
`i`	类型： String 必需。区分大小写。建议使用反向 DNS 表示法。为您的游戏指定的唯一游戏标识符。必须与会话通知和 Web SDK Product ID 中使用的值一致。示例： `com.singular.game`
`sdid`	类型： UUIDv4 必需。用于标识唯一游戏安装的 Singular Device ID。必须与会话通知中使用的 SDID 一致。示例： `49c2d3a6-326e-4ec5-a16b-0a47e34ed953`
`n`	类型： String 必需。最多 32 个 ASCII 字符。标识游戏内动作或里程碑的事件名称。推荐：使用 Singular 标准事件名称以实现自动的合作伙伴集成。示例： `sng_achievement_unlocked`
`os`	类型： String 必需。支持自定义值。操作系统或游戏系统。必须与会话通知中使用的值一致。示例： `windows`
`install_source`	类型： String 必需。支持自定义值。游戏商店或分发方式。必须与会话通知中使用的值一致。示例： `steam`
`ip`	类型： String 必需。 IPv4 或 IPv6 格式。如果设置了 `use_ip=true` 则不需要。事件发生时设备的 IP 地址。示例： `172.58.29.235`

可选参数

支持以下可选参数。

参数	详情
`e`	类型： JSON 可选。经过 URL 编码的 JSON，每个属性最多 500 个 ASCII 字符。提供有关事件丰富信息的自定义事件属性。推荐：使用 Singular 标准属性名称以实现合作伙伴兼容性。示例： `%7B%22sng_attr_content_id%22%3A5581%7D`
`is_revenue_event`	类型： Boolean 收入事件必需。将事件标记为收入事件。如果事件名称为 `__iap__` 或提供了非零的 `amt` ，则可以省略。示例： `true`
`amt`	类型： Number 收入事件必需。收入事件的货币金额。与 `cur` 参数配合使用。示例： `2.51`
`cur`	类型： String 收入事件必需。收入事件的 ISO-4217 三字母货币代码。与 `amt` 参数配合使用。参考： ISO-4217 货币代码示例： `EUR`
`av`	类型： String 可选。应用版本或游戏构建标识符。示例： `1.1.5.581823a`
`global_properties`	类型： JSON 可选。经过 URL 编码的 JSON。最多 5 个属性，每个最多 200 个字符。为用户保存的键值对。如果已设置，则必须在所有后续请求中持续保留。示例： `%7B%22key1%22%3A%22value1%22%7D`
`utime`	类型： Integer 可选。 UNIX 时间戳（秒）。以 UNIX 时间表示的事件时间戳。示例： `1483228800`
`umilisec`	类型： Integer 可选。 UNIX 时间戳（毫秒）。以 UNIX 时间表示的事件时间戳。示例： `1483228800000`
`ve`	类型： String 可选。示例： `9.2` 会话发生时设备的操作系统版本。
`ua`	类型： String 可选。经过 URL 编码的 User Agent 字符串。原始： `Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...` 示例： `Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...`
`use_ip`	类型： Boolean 可选。指示 Singular 从 HTTP 请求中提取 IP 地址，而不是从 `ip` 参数中提取。限制：阻止 Singular 进行基于 IP 的地理定位。通过 `country` 参数提供两字母国家/地区代码。与 `ip` 参数互斥——请勿同时使用两者。必须提供 `ip` 或 `use_ip` 之一，以避免数据被拒绝。示例： `true`
`data_sharing_options`	类型： JSON 可选。经过 JSON URL 编码的最终用户数据共享同意。必须持久保存，并在所有后续的 SESSION 和 EVENT 请求中传递。用户已同意（选择加入）：用户已拒绝（选择退出）：示例： `%7B%22limit_data_sharing%22%3Atrue%7D` `{"limit_data_sharing":false}` `{"limit_data_sharing":true}`
`custom_user_id`	类型： String 可选。用于跨设备追踪的您的内部用户 ID。禁止 PII：请勿传递个人身份信息。请使用经过哈希处理或以其他方式匿名化的内部标识符，而不是原始的电子邮件地址、电话号码或姓名。示例： `123456789abcd`

请求示例

示例实现

标准事件

curl -X POST "https://s2s.singular.net/api/v2/evt" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --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 -X POST "https://s2s.singular.net/api/v2/evt" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --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/v2/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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
    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/v2/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.post(url, data=params, headers={'Content-Type': 'application/x-www-form-urlencoded'})
    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/v2/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, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: 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/v2/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, {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: 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 和主机游戏归因常见问题解答
标准事件： Singular 标准事件参考

PC 与主机 - API 端点参考

PC 与主机 API 端点参考

会话通知端点

端点规范

用途

会话参数

必需参数

可选参数

请求示例

示例实现

基本会话请求

使用 Match ID 的首次启动

基本会话请求

使用 Match ID 的首次启动

基本会话请求

使用 Match ID 的首次启动

事件通知端点

端点规范

用途

事件参数

必需参数

可选参数

请求示例

示例实现

标准事件

收入事件

标准事件

收入事件

标准事件

收入事件

响应处理

响应格式

其他资源