PC 与主机 API 端点参考

完整的 PC 和主机 server-to-server 端点 API 参考，为会话追踪和事件上报提供详细的参数规范和实现示例。

共享 S2S 参数： 端点、身份验证和通用请求参数在 S2S 基础知识中心中统一定义。本参考仅涵盖 PC 与主机的特定内容。

企业版功能： PC 和主机游戏归因是一项企业版功能。要了解更多信息，请阅读 PC 和主机游戏归因常见问题或联系您的 Customer Success Manager。

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

会话通知端点

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

端点规范

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

用途

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

归因工作流：

首次会话： 触发针对网页广告系列点击的安装归因匹配
后续会话： 用于追踪用户活动、留存和再互动分析
实时上报： 尽可能贴近实际游戏启动时刻发送会话通知

会话参数

必需参数

身份验证使用共享的 a 参数（SDK Key）。请参阅 S2S 基础知识中心中的身份验证。

参数	详情
`p`	`string` 必需。区分大小写。用户玩游戏所在的平台。支持的值： `pc` `xbox` `playstation` `nintendo` `metaquest` 示例： `pc`
`i`	`string` 必需。区分大小写。推荐使用反向 DNS 表示法。您游戏专有的游戏标识符。关键：必须与 Web SDK Product ID 完全一致，归因才能正常工作。对同一款游戏，在所有平台上使用相同的值。示例： `com.singular.game`
`sdid`	`UUID` 必需。推荐使用 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` `epicgamestore` `microsoftstore` `gog` `humblestore` `xbox` `playstation` `nintendo` `metaquest` `selfdistributed` 支持自定义值。示例： `steam`
`ip`	`string` 必需。 IPv4 或 IPv6 格式。如果 `use_ip=true` 则无需提供。游戏启动时设备的 IP 地址。替代方案：使用 `use_ip=true` 从 HTTP 请求头中提取 IP，而无需显式传递。请参阅 S2S 基础知识中心中的网络和位置。示例： `172.58.29.235`

可选参数

通用设备属性（ ve ， ua ）、网络参数（ use_ip ）、数据隐私（ data_sharing_options ）和跨设备（ custom_user_id ）在所有 S2S 端点之间共享。请参阅 S2S 基础知识中心中的设备参数，网络和位置，数据隐私，以及跨设备。以下参数是 PC 与主机特有的。

参数	详情
`install_ref`	`string` 可选。仅限首次启动。JSON URL 编码的 Google Install Referrer 信息。为通过 Google Play Games 商店分发的原生 PC 游戏提供最准确的归因。要求：需要实现 Play Games PC SDK 以传递必须仅在首次游戏启动时发送有关实现细节，请参阅 Google Play 原生 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`

请求示例

示例实现

基本会话请求

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"

使用 Match 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'
})

使用 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.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'
});

使用 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}?${params.toString()}`);
    return await response.json();
}

事件通知端点

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

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

端点规范

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

用途

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

事件最佳实践：

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

事件参数

必需参数

身份验证使用共享的 a 参数（SDK Key）。请参阅 S2S 基础知识中心中的身份验证。

参数	详情
`p`	`string` 必需。区分大小写。用户玩游戏所在的平台。支持的值： pc, xbox, playstation, nintendo, metaquest 示例： `pc`
`i`	`string` 必需。区分大小写。推荐使用反向 DNS 表示法。您游戏专有的游戏标识符。必须与会话通知和 Web SDK Product ID 中使用的值一致。示例： `com.singular.game`
`sdid`	`UUID` 必需。用于标识唯一游戏安装的 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`

可选参数

通用设备属性（ ve ， ua ）、网络参数（ use_ip ）、数据隐私（ data_sharing_options ）和跨设备（ custom_user_id ）在所有 S2S 端点之间共享。请参阅 S2S 基础知识中心中的设备参数，网络和位置 , 数据隐私，以及跨设备。以下参数是 PC 与主机特有的。

参数	详情
`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`

请求示例

示例实现

标准事件

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 和主机游戏归因常见问题
标准事件： Singular 标准事件参考

PC 与主机 - API 端点参考

PC 与主机 API 端点参考

会话通知端点

端点规范

用途

会话参数

必需参数

可选参数

请求示例

示例实现

基本会话请求

使用 Match ID 的首次启动

基本会话请求

使用 Match ID 的首次启动

基本会话请求

使用 Match ID 的首次启动

事件通知端点

端点规范

用途

事件参数

必需参数

可选参数

请求示例

示例实现

标准事件

收入事件

标准事件

收入事件

标准事件

收入事件

响应处理

响应格式

其他资源