EVENT 端点 API 参考
作为 SDK 集成的替代方案，通过服务器对服务器集成使用 Singular 的 REST API 追踪应用内事件和收入，用于归因分析和广告系列优化。
概述
服务器对服务器使用场景
EVENT 端点用于追踪应用内事件和收入，以进行归因分析和广告系列优化。初次接触服务器对服务器集成？请参阅 S2S 基础指南 了解核心概念和通用设置。
支持的功能：
- 事件归因： 将用户行为与营销广告系列关联起来
- 收入追踪： 衡量并归因应用内购买和交易
- 自定义事件： 追踪从注册到关卡完成的任何用户互动
- 事件属性： 为事件附加上下文数据，以便进行更深入的分析
混合模式使用场景： 在混合集成中，必须使用 Singular SDK，并由其管理会话追踪，因此不使用 SESSION 端点。您的服务器使用 SDK 提供的 Singular Device ID（SDID）向 EVENT V2 端点发送事件。
关键要求
前提条件：
- 先有会话，后有事件： 在追踪任何事件之前，必须先建立 SESSION
- 顺序要求： 会话顺序无效会导致数据不一致和归因错误
事件追踪准则
请按照 Singular 关于命名规范和数据结构的最佳实践来实施事件追踪。
事件定义
定义事件
在实施 S2S 集成之前，请先定义贵组织希望追踪以用于广告系列效果分析的完整事件列表。
事件规划指南： 定义应用内事件
事件命名的影响： 传递给 Singular 的事件名称直接决定了事件在报表、数据导出和回传中的呈现方式。
标准事件命名
最佳实践：
- 标准事件： 使用 Singular 的标准事件命名规范 ，以简化合作伙伴集成的映射
- 使用英文： 请以英文传递事件名称，以确保与第三方合作伙伴和分析解决方案的兼容性
- 标准属性： 事件属性请使用 标准事件属性名称
字符限制
长度限制：
- 事件名称： 最多 32 个 ASCII 字符（非 ASCII 字符转换为 UTF-8 后为 32 字节）
- 事件属性： 每个属性键和值最多 500 个 ASCII 字符
选择端点
EVENT 端点有两个版本。请使用下方的折叠面板查看各版本的端点 URL 和必需的设备标识符。其余所有参数均为通用参数，仅在下方的 必填参数 和 可选参数 中记录一次。
自 2026 年 7 月 15 日起必须使用 V2。 2026 年 7 月 15 日及之后创建的账户必须使用 Event Endpoint V2（基于 SDID）；新账户无法使用 V1。已完成 V1 集成的现有客户不受影响。如需迁移到 V2，请联系您的 Singular 客户成功经理。
如果 Singular SDK 使用 Singular Device ID（SDID）追踪会话，且您的服务器使用同一 SDID 发送事件，请在此类混合集成中使用 V2。V2 无需使用特定平台的设备标识符。
POST https://s2s.singular.net/api/v2/evt必需的标识符：
| 参数 | 详情 |
|---|---|
sdid
|
平台：
iOS、Android、Web、PC、Xbox、PlayStation、Nintendo、MetaQuest、CTV
|
对于纯服务器端集成，或 Singular SDK 不使用 SDID、依赖特定平台设备标识符（IDFA、IDFV、AIFA、ASID 等）的混合集成，请使用 V1。
POST https://s2s.singular.net/api/v1/evt必需的标识符（至少一个）：
| 参数 | 详情 |
|---|---|
idfa
|
平台：
iOS
|
idfv
|
平台：
iOS
|
aifa
|
平台：
Android
|
asid
|
平台：
Android
|
amid
|
平台：
Android
|
oaid
|
平台：
Android
|
andi
|
平台：
Android
使用限制： 禁止在 Google Play 设备上使用，请改用 AIFA 和 ASID。仅当没有任何其他标识符可用且应用并非通过 Google Play 分发时才可发送。
示例：
|
必填参数
所有 EVENT 请求除设备标识符外，还必须包含以下必填参数。
参数格式：
所有参数必须使用 POST 方法，以
application/x-www-form-urlencoded
数据形式放在请求正文中发送。请求必须包含
Content-Type: application/x-www-form-urlencoded
标头。请勿在 JSON 请求正文中发送参数。
API 身份验证
| 参数 | 详情 |
|---|---|
a
|
类型：
字符串
重要： 请勿使用 Reporting API Key，否则请求将被拒绝。
示例：
|
设备参数
| 参数 | 详情 |
|---|---|
p
|
类型：
字符串
|
ip
|
类型：
字符串
|
ve
|
类型：
字符串
|
ma
|
平台：
iOS、Android
|
mo
|
平台：
iOS、Android
|
lc
|
平台：
iOS、Android
|
bd
|
平台：
iOS、Android
|
应用参数
| 参数 | 详情 |
|---|---|
i
|
类型：
字符串
|
app_v
|
类型：
字符串
|
att_authorization_status
|
平台：
iOS
始终必填：
即使未实施 ATT，也请传入
示例：
|
事件参数
| 参数 | 详情 |
|---|---|
n
|
类型：
字符串
|
可选参数
可选参数通过附加的上下文和功能增强事件追踪。
时间戳参数
| 参数 | 详情 |
|---|---|
utime
|
类型：
整数
|
umilisec
|
类型：
整数
|
事件属性
合作伙伴 Conversion API 支持：
若要通过 Singular 的 Conversion API 集成将这些事件转发给广告网络合作伙伴，请包含标准的可选事件属性（经过哈希处理的第一方数据，例如
eventId
和
ehash
）。请参阅
用于 Conversion API 集成的标准事件属性
。
| 参数 | 详情 |
|---|---|
e
|
类型：
JSON
|
global_properties
|
类型：
JSON
|
网络参数
| 参数 | 详情 |
|---|---|
use_ip
|
类型：
布尔值
限制事项：
示例：
|
country
|
类型：
字符串
|
ua
|
类型：
字符串
|
c
|
平台：
iOS、Android
|
cn
|
平台：
iOS、Android
|
数据隐私
| 参数 | 详情 |
|---|---|
data_sharing_options
|
类型：
JSON
|
dnt
|
平台：
iOS、Android
|
dntoff
|
平台：
iOS、Android
|
跨设备支持
| 参数 | 详情 |
|---|---|
custom_user_id
|
类型：
字符串
禁止 PII： 请勿传递个人身份信息。请使用经过哈希处理或以其他方式匿名化的内部标识符，而不是原始的电子邮件地址、电话号码或姓名。
示例：
|
SKAdNetwork 支持
| 参数 | 详情 |
|---|---|
skan_conversion_value
|
平台：
iOS
|
skan_first_call_timestamp
|
平台：
iOS
|
skan_last_call_timestamp
|
平台：
iOS
|
收入追踪
通过适当的验证和货币处理来追踪应用内购买和收入事件。
必填的收入参数
基本收入追踪
当您自行进行收入验证时，追踪收入事件所需的最少参数。
最佳实践： 在向 Singular 发送事件请求之前，请在您的服务器端与应用商店验证收入事件。如果您自行验证，则仅需这些参数。
| 参数 | 详情 |
|---|---|
is_revenue_event
|
类型：
布尔值
|
amt
|
类型：
数字
|
cur
|
类型：
字符串
|
注意：
发送
amt
参数会导致该事件被作为收入事件处理，无论
is_revenue_event
的值为何，包括
is_revenue_event=false
。如果您不希望某个事件被视为收入事件，请省略
amt
参数。若要标记没有金额的收入事件，请发送
is_revenue_event=true
。
收入验证参数
由 Singular 验证的收入
供 Singular 与应用商店执行服务器端收入验证的可选参数。
验证要求：
- 如果依赖 Singular 与应用商店进行收入验证，则为必填
- 请确认购买收据和签名值的语法正确
-
格式不正确会导致 Singular 拦截该笔收入并生成
__iapinvalid__事件
| 参数 | 详情 |
|---|---|
purchase_receipt
|
平台：
iOS、Android
|
receipt_signature
|
平台：
Android
|
purchase_product_id
|
类型：
字符串
|
purchase_transaction_id
|
类型：
字符串
|
广告收入追踪
通过发送带有固定事件名称和广告变现属性的标准 EVENT，追踪来自聚合平台（例如 AdMob、AppLovin MAX 或 ironSource）的展示级广告变现收入。广告收入使用与上文相同的 EVENT 端点。
聚合平台数据： 请直接从您的聚合平台 SDK 收集所需的广告收入属性。有关各聚合平台提供的属性，请参阅 广告收入 SDK 指南 。
广告变现收入
除标准必填参数（身份验证、设备和应用）外，广告收入事件还需要以下参数。
| 参数 | 详情 |
|---|---|
n
|
类型：
字符串
|
is_admon_revenue
|
类型：
布尔值
|
is_revenue_event
|
类型：
布尔值
|
amt
|
类型：
数字
|
cur
|
类型：
字符串
|
e
|
类型：
JSON
可选属性：
JSON 结构： URL 编码示例： 注意： 没有值的属性请省略。 |
请求示例
示例代码演示了多种编程语言下的 EVENT 端点集成。
示例免责声明：
代码示例可能未包含所有必填参数。在生产环境中实施之前，请验证完整的参数列表。开发/测试请使用唯一的
i
（应用标识符）。
Python 示例
import requests
url = 'https://s2s.singular.net/api/v1/evt'
headers = {'Content-Type': 'application/x-www-form-urlencoded'}
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.post(url, data=params, headers=headers)
print(response.json())cURL 示例
curl -X POST "https://s2s.singular.net/api/v1/evt" \
-H "Content-Type: application/x-www-form-urlencoded" \
--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 示例
POST /api/v1/evt HTTP/1.1
Host: s2s.singular.net
Content-Type: application/x-www-form-urlencoded
Accept: application/json
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_cartJava 示例
// Endpoint
String endpoint = "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 form-urlencoded body
StringBuilder form = new StringBuilder();
for (Map.Entry<String, String> entry : params.entrySet()) {
if (form.length() > 0) form.append('&');
form.append(URLEncoder.encode(entry.getKey(), StandardCharsets.UTF_8))
.append('=')
.append(URLEncoder.encode(entry.getValue(), StandardCharsets.UTF_8));
}
byte[] body = form.toString().getBytes(StandardCharsets.UTF_8);
// Create connection
URL url = new URL(endpoint);
HttpURLConnection conn = (HttpURLConnection) url.openConnection();
conn.setRequestMethod("POST");
conn.setDoOutput(true);
conn.setRequestProperty("Content-Type", "application/x-www-form-urlencoded");
conn.setRequestProperty("Accept", "application/json");
// Write body
try (OutputStream os = conn.getOutputStream()) {
os.write(body);
}
// 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();
System.out.println("HTTP Status Code: " + responseCode);
System.out.println("Response: " + response.toString());
conn.disconnect();响应代码与错误
EVENT 端点返回 HTTP 状态代码和 JSON 响应，用于指示请求成功或失败。
完整错误文档： S2S 响应代码与错误处理
测试与验证
在部署到生产环境之前，请使用 Singular SDK Console 进行实时数据验证，以确认 S2S 事件集成。
测试步骤
端到端验证
- 注册测试设备： 获取设备广告 ID 并添加到 Singular SDK Console
- 启用控制台日志： 在 SDK Console 中添加设备标识符以捕获测试数据
-
使用开发版 App ID：
用开发版本覆盖应用标识符（例如
com.singular.app.dev），以将测试数据与生产数据分开 - 构建并启动： 从完全关闭状态构建或打开应用
- 验证客户端数据： 确认应用向您的服务器发送了所有必需的 Singular 数据点
-
验证会话：
确认您的服务器已将 SESSION 请求连同所有必填参数发送至
https://s2s.singular.net/api/v1/launch - 检查 SDK Console（会话）： 数秒内，SESSION 事件应出现在 SDK Console 中
事件测试
- 触发事件： 继续在应用中触发一个事件
- 验证事件数据： 确认事件已连同所有必需的 Singular 数据点发送至您的服务器
-
验证服务器请求：
确认您的服务器已将 EVENT 请求连同所有必填参数发送至您的端点（V2
https://s2s.singular.net/api/v2/evt或 V1https://s2s.singular.net/api/v1/evt）。 - 检查 SDK Console（事件）： 数秒内，EVENT 应出现在 SDK Console 中
- 重复测试： 验证发送的所有事件均具有预期值
关键验证项：
- 确认在收到 EVENT 之前，应用打开/切换到前台时已发生 SESSION 事件
- 确认 EVENT 的必需数据点与 SESSION 的数据点一致
成功标志： 如果事件出现在 SDK Console 中，说明您已成功完成端到端事件集成测试！
其他资源
测试文档
完整测试指南： S2S 集成测试指南