文档

跟踪广告收入 API 参考

服务器到服务器用例

Singular可通过EVENT API追踪广告收入。通过使用付费的事件处理程序将印象级收入详情从调解平台转发到服务器，Singular 可以处理这些数据，以便无缝集成到报告、导出日志和回传中。该平台还支持根据企业的首选设置进行自动货币转换。

作为 SDK 的替代方案，Singular REST API 可实现服务器到服务器的直接集成。SDK 可自动收集设备和应用程序数据，而 S2S 方法则要求您：1：

从您的应用程序中收集所需的 EVENT API 数据点
收集相关的调解平台数据点
将这些数据转发到您的服务器
通过 REST API 向 Singular 发送"__ADMON_USER_LEVEL_REVENUE__"事件

关键点

灵活性：完全控制数据收集和传输
功能对等：在提供适当数据的情况下，支持所有 SDK 功能
集成路径：客户端 → 服务器 → Singular API
实时处理：一次一个请求，无批量处理
顺序数据流：事件必须按时间顺序处理
重复数据删除： Singular不会重复接收数据。建议发送一个（1）成功的请求并保存日志，以备重放请求。
数据验证： 设备级数据是永久性的，一旦接收就无法删除。在向 Singular 发送数据之前，请执行全面的数据验证，以确保数据的准确性。

前提条件

在接收任何事件跟踪之前，必须先建立会话
无效的会话顺序会导致数据不一致
直接从 Mediation SDK 收集调解平台数据属性。有关实施细节和所需数据点，请参阅我们的SDK 指南和特定平台的 Mediation 文档。

开始使用

EVENT 端点文档提供了

必填参数
可选参数
请求示例
响应代码和错误
事件测试

这种服务器端方法可让您对集成进行更多控制，同时保持 SDK 的所有功能。

事件 API 端点

HTTP 方法和事件端点

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

所需参数

下表列出了通过事件 API发送广告货币化收入事件所需的参数。这些参数应包含在查询参数中。

GET /api/v1/evt?param1=value1&param2=value2

EVENT API 请求中必须包含所有必需参数
参数应遵循指定的格式和数据类型

所需参数
API 密钥
参数	说明
`a`	`string` a参数指定 Singular SDK 密钥。请从 Singular UI 的主菜单 "开发工具"下获取 SDK 密钥。注意：请勿使用报告 API 密钥，否则会导致数据被拒绝。示例值： `sdkKey_afdadsf7asf56`
设备标识符参数
参数	支持的平台
`idfa` 支持的平台： iOS	`string` idfa参数指定了广告商标识符 (IDFA)，可帮助广告商跟踪用户操作（如广告点击、应用安装）并将其归属于特定广告系列，从而实现精确的广告定位和广告系列优化。从 iOS 14.5 开始，用户必须通过应用程序跟踪透明度 (ATT) 框架选择加入，然后应用程序才能访问 IDFA。如果用户不选择加入 IDFA，那么 IDFA 将不可用，从而限制了跟踪功能。如果 IDFA 不可用，则从请求中省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 IDFA 标识符示例值： `DFC5A647-9043-4699-B2A5-76F03A97064B`
参数	说明
`idfv` 支持的平台： iOS	`string` idfv参数指定了供应商标识符 (IDFV)，这是 Apple 分配给设备的唯一标识符，专门针对特定供应商或开发者。该标识符在特定设备上来自同一供应商的所有应用程序中保持一致，允许供应商在其应用程序生态系统中跟踪用户行为和交互，而无需识别用户个人身份。无论 ATT 状态如何或是否存在 IDFA，所有请求都需要 IDFV。如何检索 IDFV 标识符示例值： `21DB6612-09B3-4ECC-84AC-B353B0AF1334`
参数	说明
`aifa` 支持的平台：安卓 (谷歌播放设备）	`string` aifa参数指定Google Advertising Identifier (GAID)，也称为 AIFA in Singular 或 Android Advertising ID (AAID)。该标识符是分配给 Android 设备的唯一、用户可重置的标识符。它可以帮助广告商和应用程序开发商跟踪用户在应用程序中的操作（如广告点击、应用程序安装）并将其归属于特定的广告系列，从而实现精确的广告定位和广告系列优化，同时维护用户隐私。如果 AIFA 不可用，则从请求中省略该参数。仅 Google Play 设备需要。在非 Google Play 设备上请省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 AIFA 标识符示例值： `8ecd7512-2864-440c-93f3-a3cabe62525b`
参数	说明
`asid` 支持的平台：安卓 (谷歌播放设备）	`string` asid参数指定Android 应用程序集 ID。ASID 为开发者提供了一种以注重隐私的方式在自己的应用程序中跟踪用户的方法。它对分析和防止欺诈特别有用，但不能用于个性化广告或测量等广告目的。无论是否存在 GAID/AIFA，Google Play 设备的所有请求都需要 ASID。非 Google Play 设备则省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 ASID 标识符示例值： `edee92a2-7b2f-45f4-a509-840f170fc6d9`
参数	说明
`amid` 支持的平台：安卓 (无 Google Play 服务的亚马逊设备）	`string` amid参数指定的广告 ID是用户可重置的唯一标识符，有助于保护用户隐私。如果要收集用户行为信息以显示基于兴趣的广告或生成分析结果，则必须使用广告 ID；不得使用其他标识符或跟踪方法。用户可以重置广告 ID 或完全退出基于兴趣的广告。对于没有 Google Play 服务的亚马逊设备，所有请求都必须使用 AMID。如果 AMID 不可用，请省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 AMID 标识符示例值： `df07c7dc-cea7-4a89-b328-810ff5acb15d`
参数	说明
`oaid` 支持的平台：安卓 (无 Google Play 服务的中国制造设备）	`string` oaid参数指定开放式广告标识符 (OAID)。OAID 是唯一的匿名标识符，用于在 Android 设备（尤其是中国制造的设备）上发布广告。它由移动安全联盟（MSA）推出，作为谷歌广告标识符（GAID）的替代标识符，适用于不提供或不支持谷歌播放服务的设备，如中国市场上的设备。 OAID 主要用于 Google Play 服务受限环境下的广告归属和用户跟踪，允许广告商和开发商在保持匿名性的同时跟踪用户行为。大多数中国制造的安卓设备都可以使用 OAID，包括华为、小米等品牌的设备。可以使用 MSA SDK 或华为移动服务（HMS）访问它。没有 Google Play 服务的中国制造 Android 设备需要 OAID。如果 OAID 不可用，请省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 OAID 标识符示例值： `01234567-89abc-defe-dcba-987654321012`
参数	说明
`andi` 支持的平台：安卓 (非 Google Play 设备）	`string` andi参数指定 Android ID，这是一个唯一的 64 位标识符，由 Android 操作系统在首次设置设备时生成。它的设计目的是在设备的整个生命周期内保持不变，但在出厂重置等特定条件下可以重置。每个设备的 Android ID 都是唯一的，而且从 Android 8.0（奥利奥）开始，每个应用程序和每个用户都有自己的 ID。这意味着同一设备上的不同应用程序将获得不同的 Android ID，除非它们共享相同的签名密钥。除非设备进行出厂重置或在 OTA（空中下载）更新后卸载并重新安装应用程序，否则 Android ID 将保持不变。禁止在 Google Play 设备上使用 ANDI。请使用上述 AIFA 和 ASID 标识符。只有在没有其他标识符且应用程序未托管在 Google Play 商店的情况下，才能向 Singular 发送 ANDI。如果有其他标识符，请省略该参数。请勿在请求中传递 NULL 或空字符串。如何检索 ANDI 标识符示例值： `fc8d449516de0dfb`
设备参数
参数	说明
`p`	`string` p参数指定应用程序的平台。下面列出了允许使用的区分大小写的参数值：安卓 iOS 示例值： `Android`
参数	说明
`ip`	`string` ip参数指定设备的公共 (IPV4) IP 地址。不支持 IPV6。示例值： `172.58.29.235`
参数	说明
`ve`	`string` ve参数指定事件发生时设备的操作系统版本。示例值： `9.2`
应用程序参数
参数	说明
`i`	`string` i参数指定应用程序标识符。该值区分大小写：安卓的软件包名称 iOS 的软件包 ID 示例值： `com.singular.app`
参数	描述
`att_authorization_status` 支持的平台： iOS	`int` att_authorization_status参数指定 App Tracking Transparency(ATT) 状态代码。从 iOS 14.5 开始，访问 IDFA 标识符需要使用应用程序跟踪透明度（ATT）提示。注意：即使您不执行 ATT 提示，我们也要求您传递 ATT 授权状态，其值为"0"，表示 "未确定"。支持的值有 0 - 未确定。 1 - 限制，用户禁用应用程序跟踪。 2 - Denied（拒绝），用户拒绝授权。 3 - 已授权，用户已授权。示例： `3`
事件参数
参数	说明
`n`	`string` n参数指定跟踪事件的名称。支持 AdMon 收入要求事件名称必须是一个特定值。事件名称必须为大写字母，并带有下划线。请使用以下事件名称： `__ADMON_USER_LEVEL_REVENUE__`
参数	说明
`e`	`JSON URL-encoded string` e参数以 JSON 格式指定自定义事件属性。唯一必需的属性是 "ad_platform"。所有其他属性均为可选属性。可能的属性如下 ad_platform-- 必填 ad_mediation_platform 广告类型 ad_group_type ad_impression_id ad_placement_name ad_unit_id 广告单位名称 ad_group_id 广告组名 ad_group_priority ad_placement_id 注意：没有值的属性应省略。 `{ "ad_platform":"AdMob", "ad_mediation_platform":"admob.AdMobAdapter", "ad_unit_id":"ca-app-pub-6325336052\/44923540" }` 示例值： `%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`	`string` is_admon_revenue参数指定该事件是否为广告货币化收入事件，并应用于广告收入指标。为该事件输入 "true"。示例值 `true`
参数	说明
`is_revenue_event`	`string` is_revenue_event参数指定事件是否为收入事件，并用于收入指标。为该事件输入 "true"。示例值 `true`
参数	说明
`amt`	`double` amt参数指定货币金额。应与 "cur "参数一起使用。示例值 `0.00782`
参数	说明
`cur`	`string` cur参数指定大写ISO 4217三字母货币代码。应与 "amt "参数一起使用。示例值 `USD`

请求正文

调用此方法时，请勿提供请求正文。必须使用带查询参数的 GET 方法发送请求。

请求示例

以下代码示例可能不代表所有支持的参数。在执行请求时，请确保包含上面列出的所有所需参数，并在从生产实例发送数据前验证所传递的值是否正确。建议在开发和测试时使用唯一的应用程序标识符。

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 application-level status

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

// Disconnect

conn.disconnect();

可选参数

下表列出了该端点支持的可选参数。所有列出的参数都是查询参数。

可选参数
设备和网络参数
参数	说明
`use_ip`	`string` use_ip参数用于指示 Singular 从 HTTP 请求中提取 IP 地址，而不是使用 "ip "参数。通过"true"可使用此功能。使用该参数可以防止 Singular 根据 IP 地址对设备进行地理定位。您可以在可选的 "country "参数中提供用户的双字母国家代码。该参数与 "ip "参数互斥。切勿与 "ip "参数一起使用。为避免数据被拒绝，您必须在请求中提供 "ip "或 "use_ip "参数。示例值： `true`
参数	说明
`country`	`string` country参数应包含事件执行时用户的ISO 3166-1 alpha-2 双字母国家代码。只有在以下情况下才需使用此参数没有 "ip "参数如果 "ip "参数可用，则将根据 IP 地址自动确定国家，不需要 "country "参数。示例值： `US`
数据隐私
参数	说明
`data_sharing_options`	`JSON URL-encoded string` data_sharing_options参数用于指定最终用户是否同意共享信息。如果设置了该值，则必须在用户以后的每次 "会话 "和 "事件 "请求中持续传递该值。若要表示用户同意（opted-in）共享其信息，则输入 "false"： `{"limit_data_sharing":false}` 如果用户拒绝，则传递 "true"： `{"limit_data_sharing":true}` 值必须是 URL 编码的 JSON 字符串。示例值： `%7B%22limit_data_sharing%22%3Atrue%7D`
跨设备支持
参数	说明
`custom_user_id`	`string` 自定义用户ID 参数用于指定内部用户 ID。示例值： `123456789abcd`

事件测试

在完成服务器到服务器的集成后，必须在生产实例上线前验证 Singular 是否能接收数据。详情请参考我们的测试指南。一般来说，应遵循以下步骤：

获取测试设备的广告 ID，并在 Singular SDK 控制台中添加该 ID。
打开 Singular SDK 控制台，添加设备标识符以开始捕获数据。
用开发应用程序标识符（com.singular.app.dev）覆盖应用程序标识符，将测试数据和事件与生产数据分开。
从终止状态构建或打开应用程序
验证 "应用程序打开 "与所有必要的 Singular 数据点一起发送到服务器
验证服务器会触发会话通知到 Singular 的"启动"端点，并包含所有必要的数据点。
几秒钟后，会话事件就会显示在 Singular SDK 控制台中。
继续在应用程序中触发事件。
验证事件是否已发送到服务器，并包含所有必要的 Singular 数据点
验证您的服务器是否触发了事件通知，并将所有必要的数据点发送到 Singular的 "evt"端点。
几秒钟后，事件就会显示在 Singular SDK 控制台中。
重复测试，以验证所有事件都按预期发送，并带有预期值。

重要验证

确认会话事件发生在应用程序打开或转到前台以及收到事件之前。
确认事件所需数据点与会话数据点匹配。
确认在事件参数中传递了正确的调解平台详细信息
确认正确的收入金额和货币

如果您在 SDK 控制台中看到了事件，说明您已经完成了事件处理的端到端测试！

服务器到服务器跟踪广告收入 API 参考

跟踪广告收入 API 参考

服务器到服务器用例

关键点

前提条件

开始使用

事件 API 端点

所需参数

请求正文

请求示例

PYTHON

CURL

HTTP

JAVA 示例

可选参数

事件测试