EVENT 端点 API 参考

通过服务器到服务器集成，使用 Singular 的 REST API 追踪应用内事件和收入，用于归因分析和广告系列优化，作为 SDK 实现的替代方案。

概述

服务器到服务器用例

EVENT API 支持应用内事件追踪，应用将用户交互数据转发到您的后端，再由后端传输到 Singular 的服务器，用于事件归因和收入分析报告。

支持的功能：

事件归因： 将用户行为与营销广告系列相关联
收入追踪： 衡量并归因应用内购买和交易
自定义事件： 追踪任何用户交互，从注册到关卡完成
事件属性： 为事件附加上下文数据，实现更深入的分析

数据流架构

服务器到服务器事件追踪遵循四步数据传输流程。

客户端收集： 应用收集事件数据和设备标识符
服务器传输： 应用将事件数据转发到您的后端服务器
设备图谱查询： 服务器从 Singular 设备图谱中检索或更新设备详情
Event API 调用： 服务器将事件发送到 Singular REST API 端点

事件数据流示意图

关键要求

前提条件：

事件之前的会话： 在任何事件追踪之前，必须先建立 SESSION
顺序： 无效的会话顺序会导致数据不一致和归因错误

集成约束：

实时处理： 请求逐个处理，不支持批量处理
按时间顺序的事件： 事件必须按其发生的顺序发送
无去重： Singular 不对数据去重，请在服务器端实现去重以防止重复
数据永久性： 设备级数据一经摄取即无法删除，发送前请先验证

事件追踪指南

按照 Singular 关于命名规范和数据结构的最佳实践实现事件追踪。

事件定义

定义事件

在实现 S2S 集成之前，请定义您的组织希望追踪的完整事件列表，用于广告系列效果分析。

事件规划指南：定义应用内事件

事件命名的影响： 传递给 Singular 的事件名称直接决定了事件在报告、导出和回传中的显示方式。

标准事件命名

最佳实践：

标准事件： 使用 Singular 的标准事件命名规范以简化合作伙伴集成映射
英语： 以英语传递事件名称，以兼容第三方合作伙伴和分析解决方案
标准属性： 为事件属性使用标准事件属性名称

字符限制

长度限制：

事件名称： 最多 32 个 ASCII 字符（对于非 ASCII 字符，转换为 UTF-8 后为 32 字节）
事件属性： 每个属性键和值最多 500 个 ASCII 字符

API 端点选择

Singular 提供两个 EVENT 端点版本，针对不同的集成架构进行了优化。

端点选择： 根据您的集成架构和设备标识符策略选择端点。用例决定正确的端点。

Event Endpoint V1

V1 用例

对于依赖平台特定设备标识符（IDFA、IDFV、AIFA、ASID 等）的集成，请使用 Event Endpoint V1。

推荐用于：

纯服务器端： 未实现 Singular SDK 的服务器端集成
混合（非 SDID）： Singular SDK 不使用 Singular Device ID (SDID) 的混合集成

端点 URL：

GET https://s2s.singular.net/api/v1/evt

Event Endpoint V2

V2 用例

对于 Singular SDK 使用 SDID 追踪会话且服务器使用相同 SDID 发送事件的混合集成，请使用 Event Endpoint V2。

推荐用于：

混合（基于 SDID）： Singular SDK 使用 SDID 追踪会话，且服务器端事件使用相同的 SDID
简化标识符： 避免使用平台特定设备标识符（IDFA、AIFA 等）的实现

端点 URL：

GET https://s2s.singular.net/api/v2/evt

账户启用： V2 端点需要 Singular 账户配置以使用 SDID。请联系您的 Solution Engineer 或 CSM 进行启用。

Web (p=Web) 变体

Web 集成使用同一个 EVENT 端点，并带 p=Web 。不存在 Web SESSION 调用：第一个带 conversion_event=true 的 __PAGE_VISIT__ 事件将取代启动，建立归因触点。

完整指南： 有关完整的浏览器辅助模式（SDID 持久化、 __PAGE_VISIT__ 排序、Web 到应用，以及剪贴板延迟深度链接），请参阅 Web S2S 实现指南。

Web 专用参数

这些参数在 p=Web 时适用。共享参数（ a 、 i 、 ip 、 sdid 、 custom_user_id ）在 S2S 基础中定义。

参数	详情
`conversion_event`	`boolean` 仅在 `__PAGE_VISIT__` 归因事件上设为 `true` ；在所有其他 Web 事件上设为 `false` 。在其归因事件之前到达的非归因事件会被短暂延迟以等待匹配。示例： `true`
`attribution_data`	`JSON` 从落地页 URL 解析出的广告系列数据的 URL 编码 JSON，在 `__PAGE_VISIT__` 事件上发送。有关字段映射，请参阅 attribution_data 和 Web 点击 ID 。示例： `%7B%22partner_name%22%3A%22Snapchat%22%2C%22is_attributed%22%3A%22true%22%7D`
`web_url`	`string` 包含营销参数（UTM / `wp` / `pc` ）的广告系列落地页 URL。用于归因（触点创建）。示例： `http://my.landing.page/?utm_campaign=test&utm_source=test`
`web_page_referrer`	`string` 引荐来源（ `document.referrer` ）。用于自然量来源/类型分类。示例： `https://www.google.com/`

Web 点击 ID： 在事件 e 参数中传递合作伙伴点击 ID （ ScCid 、 ttclid 、 gclid / gbraid / wbraid 、 dclid 、 fbclid 、 rdt_uuid ）。

必需的设备标识符

设备标识符要求因端点版本和平台而异。请查看下方的平台特定要求。

V1 端点标识符

平台特定标识符

Event Endpoint V1 需要基于设备操作系统和应用分发方式的平台特定广告标识符。

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

V2 端点标识符

仅需 SDID

Event Endpoint V2 在所有平台上仅需 Singular Device ID (SDID)，简化了设备识别。

参数详情


        sdid

平台： iOS、Android、Web、PC、Xbox、 PlayStation、Nintendo、MetaQuest、CTV

从 Singular SDK 获取或在客户端生成的 Singular Device ID。

iOS/Android： 需要启用账户以使用 SDID —— SDK 回调方法在初始化后提供 SDID
标识符简化： 无需 AIFA、ASID、IDFA、IDFV 参数
Web： 从 Singular Web SDK 获取
PC/游戏主机/CTV： 客户端生成的 UUIDv4，代表唯一的应用安装
获取 SDID

示例： 40009df0-d618-4d81-9da1-cbb3337b8dec

必需参数

除设备标识符外，所有 EVENT 请求都必须包含这些必需参数。

参数格式： 所有参数都必须使用 GET 方法作为 URL 查询参数传递。请勿在 JSON 请求正文中发送参数。

API 身份验证

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

设备参数

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

应用参数

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

事件参数

参数	详情
`n`	`string` 所追踪事件的名称。最多 32 个 ASCII 字符（UTF-8 为 32 字节）建议：使用标准事件命名规范示例： `sng_add_to_cart`

可选参数

可选参数通过附加的上下文和功能增强事件追踪。

时间戳参数

参数详情


        utime

integer

事件的 10 位 Unix 时间戳。

示例： 1483228800


        umilisec

integer

带毫秒的 13 位 Unix 时间戳。

示例： 1483228800000

事件属性

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

参数详情

JSON

指定自定义事件属性的 JSON URL 编码字符串。

JSON 结构：

{
  "sng_attr_content_id": 5581,
  "sng_attr_content": "XBox",
  "sng_attr_content_type": "electronics"
}

建议：使用标准属性命名规范
每个属性键和值最多 500 个 ASCII 字符

URL 编码示例：

%7B%22sng_attr_content_id%22%3A5581%2C%22sng_attr_content%22%3A%22XBox%22%2C%22sng_attr_content_type%22%3A%22electronics%22%7D


        global_properties

JSON

包含自定义键值对的 JSON URL 编码对象，全局应用于事件。

限制：

最多 5 个键值对
每个键和值最多 200 个字符

JSON： {"key1":"value1","key2":"value2"}

URL 编码： %7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D

网络参数

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

数据隐私

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

跨设备支持

这些是共享的 S2S 参数，在 S2S 基础中统一定义。

SKAdNetwork 支持

参数详情


        skan_conversion_value

iOS

integer

事件发生时的最新 SKAdNetwork 转化值。

了解更多： SKAdNetwork 实现

示例： 7


        skan_first_call_timestamp

iOS

integer

首次调用 SKAdNetwork API 的 Unix 时间戳。

示例： 1483228800


        skan_last_call_timestamp

iOS

integer

事件发生时最近一次调用 SKAdNetwork API 的 Unix 时间戳。

示例： 1483228800

收入追踪

通过正确的验证和货币处理来追踪应用内购买和收入事件。

必需的收入参数

基本收入追踪

当您自行进行收入验证时，收入事件追踪所需的最少参数。

最佳实践： 在向 Singular 发送事件请求之前，先在您的服务器端与 App Store 验证收入事件。如果自行进行验证，则仅需这些参数。

参数详情


        is_revenue_event

boolean

指定事件是否为收入事件。

如果事件名称为 __iap__ 或提供了非零的 amt ，则可省略

示例： true

amt

number

交易的货币金额。

与 cur 参数配合使用

示例： 2.51

cur

string

ISO 4217 三字母大写货币代码。

与 amt 参数配合使用

示例： USD

收入验证参数

Singular 验证的收入

供 Singular 与 App Store 进行服务器端收入验证的可选参数。

验证要求：

如果依赖 Singular 与 App Store 进行收入验证，则为必需
确认购买收据和签名值的语法正确
格式不正确会导致 Singular 拦截收入并生成 __iapinvalid__ 事件

参数	详情
`purchase_receipt` iOS, Android	`JSON` 从购买交易中收到的收据。 Android： Google Play Billing Library Purchase object iOS： StoreKit app receipt 示例 (iOS)： `MIISqwYJKoZI...cNqts0jvcNvPcK7yuj0KhJ9nTTQ54kDKfReihzc6aw==` 示例 (Android，URL 编码)： `%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22...`
`receipt_signature` Android	`string` 用于签署购买收据的签名（仅限 Android）。示例： `TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==`
`purchase_product_id`	`string` 产品 SKU 标识符。示例： `com.example.product`
`purchase_transaction_id`	`string` 交易标识符。示例 (iOS)： `380000123004321` 示例 (Android)： `GPA.1234-1234-1234-12345`

请求示例

示例代码演示了 EVENT 端点在多种编程语言中的集成。

示例免责声明： 代码示例可能未包含所有必需参数。在生产环境实现前，请验证完整的参数列表。请为开发/测试使用唯一的 i （应用标识符）。

Python 示例

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'ma': 'samsung',
    'mo': 'SM-G935F',
    'lc': 'en_US',
    'bd': 'Build/13D15',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': 'sng_add_to_cart'
}

response = requests.get('https://s2s.singular.net/api/v1/evt', params=params)
print(response.json())

cURL 示例

curl -G "https://s2s.singular.net/api/v1/evt" \
  --data-urlencode "a=sdk_key_here" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.singular.app" \
  --data-urlencode "ip=10.1.2.3" \
  --data-urlencode "ve=9.2" \
  --data-urlencode "ma=samsung" \
  --data-urlencode "mo=SM-G935F" \
  --data-urlencode "lc=en_US" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=sng_add_to_cart"

HTTP 示例

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &ma=samsung
    &mo=SM-G935F
    &lc=en_US
    &bd=Build%2F13D15
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=sng_add_to_cart HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Java 示例

// Base URL
String baseUrl = "https://s2s.singular.net/api/v1/evt";

// Parameters
Map<String, String> params = new HashMap<>();
params.put("a", "sdk_key_here");
params.put("p", "Android");
params.put("i", "com.singular.app");
params.put("ip", "10.1.2.3");
params.put("ve", "9.2");
params.put("ma", "samsung");
params.put("mo", "SM-G935F");
params.put("lc", "en_US");
params.put("bd", "Build/13D15");
params.put("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "sng_add_to_cart");

// Build URL with encoded parameters
StringBuilder urlBuilder = new StringBuilder(baseUrl);
urlBuilder.append('?');

for (Map.Entry<String, String> entry : params.entrySet()) {
    if (urlBuilder.length() > baseUrl.length() + 1) {
        urlBuilder.append('&');
    }
    urlBuilder.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
        .append('=')
        .append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}

// Create connection
URL url = new URL(urlBuilder.toString());
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("GET");
conn.setRequestProperty("Accept", "application/json");

// Get response
int responseCode = conn.getResponseCode();
BufferedReader in = new BufferedReader(
    new InputStreamReader(conn.getInputStream())
);

String inputLine;
StringBuilder response = new StringBuilder();
while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
}
in.close();

// Check status
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());

// Disconnect
conn.disconnect();

响应代码和错误

EVENT 端点返回 HTTP 状态代码和 JSON 响应，指示请求成功或失败。

完整的错误文档： S2S 响应代码和错误处理

测试和验证

在生产部署之前，使用 Singular SDK Console 进行实时数据验证，以验证 S2S 事件集成。

测试流程

端到端验证

注册测试设备： 获取设备广告 ID 并添加到 Singular SDK Console
启用 Console 日志记录： 在 SDK Console 中添加设备标识符以捕获测试数据
使用开发版应用 ID： 用开发版本覆盖应用标识符（例如 com.singular.app.dev ），以将测试数据与生产数据分离
构建并启动： 从终止状态构建或打开应用
验证客户端数据： 确认应用将所有必需的 Singular 数据点发送到您的服务器
验证会话： 确认您的服务器将 SESSION 请求发送到 https://s2s.singular.net/api/v1/launch ，并带所有必需参数
检查 SDK Console（会话）： 几秒钟内，SESSION 事件应出现在 SDK Console 中

SDK Console 会话事件

事件测试

触发事件： 继续在应用中触发事件
验证事件数据： 确认事件已带所有必需的 Singular 数据点发送到您的服务器
验证服务器请求： 确认您的服务器将 EVENT 请求发送到 https://s2s.singular.net/api/v1/evt ，并带所有必需参数
检查 SDK Console（事件）： 几秒钟内，EVENT 应出现在 SDK Console 中
重复测试： 验证所有事件均以预期值发送

SDK Console 事件

关键验证：

确认在收到 EVENT 之前，应用打开/进入前台时发生了 SESSION 事件
确认 EVENT 的必需数据点与 SESSION 的数据点相匹配

成功指示： 如果事件出现在 SDK Console 中，说明您已完成成功的端到端事件集成测试！

其他资源

测试文档

全面的测试指南： S2S 集成测试指南

Server-to-Server - EVENT 端点 API 参考

EVENT 端点 API 参考

概述

服务器到服务器用例

数据流架构

关键要求

事件追踪指南

事件定义

定义事件

标准事件命名

字符限制

API 端点选择

Event Endpoint V1

V1 用例

Event Endpoint V2

V2 用例

Web (p=Web) 变体

Web 专用参数

必需的设备标识符

V1 端点标识符

平台特定标识符

V2 端点标识符

仅需 SDID

必需参数

API 身份验证

设备参数

应用参数

事件参数

可选参数

时间戳参数

事件属性

网络参数

数据隐私

跨设备支持

SKAdNetwork 支持

收入追踪

必需的收入参数

基本收入追踪

收入验证参数

Singular 验证的收入

请求示例

Python 示例

cURL 示例

HTTP 示例

Java 示例

响应代码和错误

测试和验证

测试流程

端到端验证

事件测试

其他资源

测试文档