EVENT 端点 API 参考

服务器到服务器用例

EVENT API 可在您的应用程序中实现事件跟踪。当您的应用程序将特定于设备的数据转发给您的服务器，然后由服务器将其传输到 Singular 的服务器时，平台会处理这些信息，以便进行以下操作：事件归因和应用程序收入指标。这些经过处理的数据会自动填充到您的报告、导出日志和配置的回传中，为您的营销活动提供全面的分析。

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

从您的应用程序中收集所需的数据点
将这些数据转发到您的服务器
从设备图更新/获取设备详细信息
通过 REST API 将事件转发给 Singular

关键点

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

前提条件

在接收任何事件跟踪之前，必须先建立会话
无效的会话顺序会导致数据不一致

开始使用

EVENT 端点文档提供

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

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

报告事件

Singular 可以收集有关应用程序内事件的数据，帮助分析营销活动的效果。事件可以包括任何用户交互，从登录和注册到游戏应用程序中的等级提升。

在实施与 Singular 的 SDK/S2S 集成之前，您应该有一份贵组织希望跟踪的事件列表（请参阅定义应用程序内事件）。

您在调用中包含的事件名称将在 Singular 报告、导出和回传中被识别。

注意：

Singular 建议使用Singular 的标准事件和属性命名约定传递事件。使用标准事件可以简化映射，并在集成中与合作伙伴的标准事件兼容。
我们强烈建议使用英文传递事件名称和其他属性，以便与第三方合作伙伴和分析解决方案兼容。

重要：

事件名称限制为 32 个 ASCII 字符。对于非 ASCII 字符，转换为 UTF-8 后限制为 32 字节。
事件属性和值限制为 500 个 ASCII 字符。

事件 API 端点

HTTP 方法和事件端点

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

所需参数

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

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`
参数	说明
`sdid` 支持的平台：网络电脑 Xbox 游戏机任天堂元探索 CTV	`string` sdid参数指定奇异设备 ID。对于网络事件，该值可从 Singular Web SDK 获取。如何检索网络 SDID 标识符对于 PC 和控制台应用程序，该值是客户端生成的 UUIDv4，代表唯一的应用程序安装。示例值： `40009df0-d618-4d81-9da1-cbb3337b8dec`
参数	说明
`sing` 支持的平台：仅限特殊用例更多信息，请联系您的解决方案工程师或 CSM	`string` sing参数仅限企业客户使用，用于指定客户端定义的标识符。仅用于无法使用所有其他标识符的特殊用途。该标识符必须由 Singular 解决方案工程师逐个应用程序启用。示例值： `da534a95-1b1b-47d4-94b6-07955ec85177`
设备参数
参数	说明
`p`	`string` p参数指定应用程序的平台。下面列出了允许使用的区分大小写的参数值：安卓 iOS 网络电脑游戏机游戏机任天堂元探索 CTV 示例值： `Android`
参数	说明
`ip`	`string` ip参数指定设备的公共 (IPV4) IP 地址。不支持 IPV6。示例值： `172.58.29.235`
参数	说明
`ve`	`string` ve参数指定事件发生时设备的操作系统版本。示例值： `9.2`
参数	描述
`ma` 支持的平台：安卓 iOS	`string` ma参数指定设备硬件的 Make，通常是面向消费者的名称。该参数必须与型号参数一起使用。如何检索设备制造商举例说明： `Samsung, LG, Apple`
参数	说明
`mo` 支持的平台：安卓 iOS	`string` mo参数指定设备硬件的型号。该参数必须与 make 参数一起使用。如何检索设备型号举例说明： `iPhone 4S, Galaxy SIII`
参数	说明
`lc` 支持的平台：安卓 iOS	`string` lc参数指定设备的 IETF 本地化标记，使用下划线分隔的双字母语言和国家代码。如何检索设备地域示例值： `en_US`
参数	说明
`bd` 支持的平台：安卓 iOS	`string` bd参数指定设备的 Build（URL 编码）。如何检索设备构建示例值： `Build%2F13D15`
应用参数
参数	说明
`i`	`string` i参数指定应用程序标识符。对于 Android 应用程序，这是软件包名称；对于 iOS 应用程序，这是软件包 ID：安卓软件包名称用于 iOS 的软件包 ID 网络版产品 ID 您为 PC、Xbox、Playstation、任天堂、MetaQuest 或 CTV 指定的标识符示例值： `com.singular.app`
参数	说明
`att_authorization_status` 支持的平台： iOS	`int` att_authorization_status参数指定 App Tracking Transparency(ATT) 状态代码。从 iOS 14.5 开始，访问 IDFA 标识符时需要使用 App Tracking Transparency (ATT) 提示。注意：即使您不执行 ATT 提示，我们也要求您传递 ATT 授权状态，其值为"0"，表示 "未确定"。支持的值有 0 - 未确定。 1 - 限制，用户禁用应用程序跟踪。 2 - Denied（拒绝），用户拒绝授权。 3 - 已授权，用户已授权。举例说明 `3`
事件参数
参数	说明
`n`	`string` n参数指定跟踪事件的名称。限制：最多 32 个 ASCII 字符建议使用 Singular 的标准事件命名约定。示例值 `sng_add_to_cart`

请求正文

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

请求示例

以下代码示例可能不代表所有支持的参数。在执行请求时，请确保包含上面列出的所有必要参数，并在从生产实例发送数据前验证所传递的值是否正确。建议使用唯一的 `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 application-level status

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

// Disconnect

conn.disconnect();

可选参数

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

可选参数
时间戳参数
参数	说明
`utime`	`int` utime参数指定事件发生的时间（10 位 UNIX 时间）。示例值： `1483228800`
参数	说明
`umilisec`	`int` umilisec参数以毫秒为单位指定事件发生时间（13 位 UNIX 时间）。示例值 `1483228800000`
设备和网络参数
参数	说明
`global_properties`	`JSON URL-encoded string` global_properties参数接受 URL 编码的 JSON 对象，最多包含 5 个键值对。每个键和值的最大长度为 200 个字符。 `{"key1":"value1","key2":"value2"}` JSON 对象必须转换为 JSON 字符串并进行 URL 编码示例值： `%7B%22key1%22%3A%22value1%22%2C%22key2%22%3A%22value2%22%7D`
参数	说明
`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`
事件参数
参数	说明
`e`	`JSON URL-encoded string` e参数以 JSON 格式指定自定义事件属性。 `{ "sng_attr_content_id":5581, "sng_attr_content":"XBox", "sng_attr_content_type":"electronics" }` 强烈建议使用 Singular 的标准事件属性命名约定。示例值： `%7B%22sng_attr_content_id%22%3A5581%2C sng_attr_content%22%3A%22XBox%22%2C%22 sng_attr_content_type%22%3A%22electronics%22%7D`
收入参数
参数	说明
`is_revenue_event`	`string` is_revenue_event参数指定事件是否为收入事件。如果事件名称是 __iap__ 或提供的金额不为零，则可以省略此参数。示例值： `true`
参数	说明
`amt`	`double` amt参数指定货币金额。应与 "cur "参数一起使用。示例值 `2.51`
参数	说明
`cur`	`string` cur参数指定大写ISO 4217三字母货币代码。应与 "amt "参数一起使用。示例值 `USD`
参数	说明
`purchase_receipt` 支持的平台：安卓 iOS	`string` purchase_receipt参数指定从购买中收到的收据。请参阅下面的说明，了解如何从 Android 和 iOS 上获取收据如何检索 Android 购买收据。如何检索 iOS 购物收据。示例 (iOS)： `MIISqwYJKoZI...cNqts0jvcNvPcK7y uj0KhJ9nTTQ54kDKfReihzc6aw==` 示例（Android）： `%7B%22orderId%22%3A%22GPA.1234%22%2C%22packageName%22%3A%22com.example%22%2C%22productId%22%3A%22com.example.product%22%2C%22purchaseTime%22%3A1417113074914%2C%22purchaseState%22%3A0%2C%22purchaseToken%22%3A%22hakfcimbk...%20pM%22%7D`
参数	说明
`receipt_signature` 支持的平台：安卓	`string` receipt_signature参数指定用于签署购买收据的签名示例值： `TyVJfHg8OAoW7W4wuJt...5agEDMnNXvhfrw==`
参数	说明
`purchase_product_id`	`string` purchase_product_id参数指定产品 SKU 识别码示例值 `com.example.product`
参数	说明
`purchase_transaction_id`	`string` purchase_transaction_id 参数指定交易标识符示例 (iOS)： `380000123004321` 示例 (Android)： `GPA.1234-1234-1234-12345`
数据隐私
参数	说明
`data_sharing_options`	`JSON URL-encoded string` data_sharing_options参数用于指定最终用户是否同意共享信息。如果设置了该值，则必须将其持久化，并在用户的每个后续 "SESSION "和 "EVENT "请求中传递。若要表示用户同意（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`
iOS SkAdNetwork 支持
参数	支持平台
`skan_conversion_value` 支持的平台： iOS	`int` skan_conversion_value参数指定此事件通知时的最新 SKAdNetwork转换值（了解有关 SKAdNetwork 实现的更多信息）。示例值： `7`
参数	说明
`skan_first_call_timestamp` 支持的平台： iOS	`int` skan_first_call_timestamp参数指定首次调用底层 SkAdNetwork API 的 Unix 时间戳（了解有关 SKAdNetwork 实现的更多信息）。示例值： `1483228800`
参数	支持的平台
`skan_last_call_timestamp` 支持的平台： iOS	`int` skan_last_call_timestamp参数指定事件通知时最近一次调用底层 SkAdNetwork API 的 Unix 时间戳（了解有关 SKAdNetwork 实现的更多信息）。示例值： `1483228800`

事件测试

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

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

重要验证

确认会话事件发生在应用程序打开或转到前台以及收到事件之前。
确认事件所需数据点与会话数据点匹配。

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