广告收入追踪 API 参考

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

本文介绍广告收入专属的参数和工作流程。共享的 S2S 端点、身份验证和通用参数在 S2S 基础知识中心统一定义。有关非广告收入的应用内事件和收入，请参阅 EVENT 端点 API 参考。

概述

服务器到服务器用例

广告收入 API 支持展示级别的广告变现追踪，应用将来自中介平台的收入数据转发到您的后端，再由后端将数据传输到 Singular 的服务器，用于广告收入分析和报告。

支持的功能：

广告变现收入： 追踪来自中介平台的展示级别收入
平台归因： 将广告收入与用户获取广告系列关联起来
中介集成： 支持所有主流广告中介平台
货币转换： 根据组织设置自动进行货币转换

数据流架构

服务器到服务器的广告收入追踪遵循四步数据传输流程。

客户端收集： 应用从中介平台 SDK 收集展示级别的收入数据
服务器传输： 应用将广告收入数据转发到您的后端服务器
设备图谱查询： 服务器从 Singular 设备图谱检索或更新设备详细信息
Event API 调用： 服务器将 __ADMON_USER_LEVEL_REVENUE__ 事件发送到 Singular REST API 端点

关键要求

前提条件：

先建立 SESSION 再发送事件： 在进行任何广告收入追踪之前，必须先建立 SESSION
顺序： 无效的会话顺序会导致数据不一致和归因错误
中介平台数据： 直接从中介 SDK 收集所需的属性——有关实现细节，请参阅 SDK 指南

集成约束：

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

API 端点选择

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

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

Event 端点 V1

V1 用例

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

推荐用于：

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

端点 URL：

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

Event 端点 V2

V2 用例

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

推荐用于：

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

端点 URL：

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

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

必需的设备标识符

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

V1 端点标识符

平台专属标识符

Event 端点 V1 需要根据设备操作系统和应用分发方式确定的平台专属广告标识符。

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

V2 端点标识符

仅需 SDID 的要求

Event 端点 V2 对所有平台仅需要 Singular Device ID (SDID)，从而简化了设备识别。

参数详细信息


        sdid

UUID

平台： iOS、Android

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

iOS/Android： 需要账户启用 SDID 使用权限——SDK 回调方法在初始化后提供 SDID
标识符简化： 无需 AIFA、ASID、IDFA、IDFV 参数
检索 SDID

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

必需参数

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

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

API 身份验证

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

设备参数

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

应用参数

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

事件参数

参数	详细信息
`n`	`string` 所追踪事件的名称。广告收入的必需事件名称： `__ADMON_USER_LEVEL_REVENUE__` 事件名称必须全部大写并使用下划线最多 32 个 ASCII 字符
`e`	`JSON` 经过 JSON URL 编码的字符串，用于指定来自中介平台的自定义事件属性。必需属性： `ad_platform` - （必需）广告网络的名称可选属性： `ad_mediation_platform` `ad_type` `ad_group_type` `ad_impression_id` `ad_placement_name` `ad_unit_id` `ad_unit_name` `ad_group_id` `ad_group_name` `ad_group_priority` `ad_placement_id` JSON 结构： `{ "ad_platform": "AdMob", "ad_mediation_platform": "admob.AdMobAdapter", "ad_unit_id": "ca-app-pub-6325336052/44923540" }` URL 编码示例： `%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%5C%2F44923540%22%7D` 注意：省略没有值的属性。
`is_admon_revenue`	`boolean` 指定该事件是否为用于广告收入指标的广告变现收入事件。为此事件传递 `true` 示例： `true`
`is_revenue_event`	`boolean` 指定该事件是否为用于收入指标的收入事件。为此事件传递 `true` 示例： `true`
`amt`	`number` 展示收入的货币金额。与 `cur` 参数结合使用示例： `0.00782`
`cur`	`string` ISO 4217 三字母大写货币代码。与 `amt` 参数结合使用示例： `USD`

可选参数

可选参数通过附加的上下文和功能来增强广告收入追踪。

网络参数

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

数据隐私

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

跨设备支持

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

请求示例

以下示例代码演示了跨多种编程语言的广告收入 EVENT 端点集成。

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

Python 示例

import requests

params = {
    'a': 'sdk_key_here',
    'p': 'Android',
    'i': 'com.singular.app',
    'ip': '10.1.2.3',
    've': '9.2',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'n': '__ADMON_USER_LEVEL_REVENUE__',
    'e': '{"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}',
    'is_admon_revenue': 'true',
    'is_revenue_event': 'true',
    'amt': 0.00782,
    'cur': 'USD'
}

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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "n=__ADMON_USER_LEVEL_REVENUE__" \
  --data-urlencode 'e={"ad_platform":"AdMob","ad_mediation_platform":"admob.AdMobAdapter","ad_unit_id":"ca-app-pub-6325336052/44923540"}' \
  --data-urlencode "is_admon_revenue=true" \
  --data-urlencode "is_revenue_event=true" \
  --data-urlencode "amt=0.00782" \
  --data-urlencode "cur=USD"

HTTP 示例

GET /api/v1/evt
    ?a=sdk_key_here
    &p=Android
    &i=com.singular.app
    &ip=10.1.2.3
    &ve=9.2
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &n=__ADMON_USER_LEVEL_REVENUE__
    &e=%7B%22ad_platform%22%3A%22AdMob%22%2C%22ad_mediation_platform%22%3A%22admob.AdMobAdapter%22%2C%22ad_unit_id%22%3A%22ca-app-pub-6325336052%2F44923540%22%7D
    &is_admon_revenue=true
    &is_revenue_event=true
    &amt=0.00782
    &cur=USD 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("n", "__ADMON_USER_LEVEL_REVENUE__");
params.put("e", "{\"ad_platform\":\"AdMob\",\"ad_mediation_platform\":\"admob.AdMobAdapter\",\"ad_unit_id\":\"ca-app-pub-6325336052/44923540\"}");
params.put("is_admon_revenue", "true");
params.put("is_revenue_event", "true");
params.put("amt", "0.00782");
params.put("cur", "USD");

// 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 会话事件

广告收入事件测试

触发广告展示： 在应用中生成广告展示以触发中介平台回调
验证中介数据： 确认展示数据已连同所有必需的中介平台属性发送到您的服务器
验证服务器请求： 确认您的服务器将 EVENT 请求发送到 https://s2s.singular.net/api/v1/evt 并包含所有必需的参数
检查 SDK Console（事件）： 在几秒钟内，__ADMON_USER_LEVEL_REVENUE__ 事件应出现在 SDK Console 中
重复测试： 验证所有广告展示均以预期值和正确的收入金额发送

SDK Console 广告收入事件

关键验证项：

确认在收到 EVENT 之前，应用打开/进入前台时发生 SESSION 事件
确认 EVENT 必需的数据点与 SESSION 数据点匹配
确认在 Event Arguments 中传递了正确的中介平台详细信息
确认收入金额和货币正确

成功标志： 如果广告收入事件出现在 SDK Console 中，则表示您已成功完成端到端广告收入集成测试！

其他资源

测试文档

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