文档

SESSION 端点 API 参考

通过 Singular 的 REST API 追踪用户会话，并启用应用安装、重新参与及留存指标的归因功能。该方案采用服务器间集成替代 SDK 实现。

概述

服务器到服务器用例

Singular REST API支持直接服务器间集成：应用程序将设备特定数据转发至您的后端，后者再传输至Singular服务器进行归因处理与分析报告。

支持功能：

安装归因：营销活动首触归因
复购归因：针对回访用户的多触点归因
留存指标：基于会话的用户行为追踪
事件追踪：自定义应用内事件测量

数据流架构

服务器间集成遵循四步数据传输流程。

客户端采集：应用程序收集所需设备及应用数据
服务器传输：应用程序将收集的数据转发至您的后端服务器
调用Singular API：您的服务器向Singular REST API接口发送数据
响应处理：您的服务器接收并处理 Singular的响应

Session Data Flow Diagram

关键考量

关键要求：

实时处理：请求单独处理——不支持批量处理
顺序要求：事件必须按时间顺序发送
无数据去重：Singular不执行数据去重需在服务器端实现去重
数据持久性：设备级数据摄入后不可删除——发送前需验证
会话优先：必须先建立会话，再进行任何事件追踪

集成优势：

灵活性：完全掌控数据采集与传输时机
功能对等：在提供正确数据时支持所有SDK功能
定制化实现：可适配特定后端架构的集成方案

会话管理

SESSION 端点通过通知应用打开事件，为归因和追踪初始化用户会话。

何时发送会话

会话触发条件

在以下应用生命周期事件时发送 SESSION 请求：

全新安装：安装后的首次应用启动
终止状态启动：应用从完全关闭状态启动
后台转前台：超时后应用返回前台（建议：60秒）

会话超时逻辑

实现会话超时机制，防止应用短暂后台运行期间产生过多SESSION请求。

推荐实现方案：

超时时长：60秒（1分钟）
若应用在超时内返回前台，则不发送SESSION请求
前台 > 超时：若应用程序在超时后仍处于后台状态，则发送SESSION请求
应用生命周期追踪： 通过应用生命周期事件与定时器管理会话状态

深度链接支持：当通过深度链接、通用链接或包含openuri 参数的App链接打开应用时，无论超时状态如何，始终发送SESSION。

归因处理

基于会话的归因

Singular处理SESSION请求以确定归因类型并触发相应工作流。

会话类型	Singular处理	归因结果
首次会话（新安装）	触发安装归因流程	将安装归因至营销活动
重新激活合格	重新参与归因流程触发	将用户返回活动或深度链接归因
标准会话	会话记录用于留存追踪	计入用户活动与互动指标

了解更多：重新参与归因常见问题解答

事件顺序要求

会话与事件的时间顺序直接影响归因准确性及数据质量。

关键排序规则：

会话优先于事件：单次会话必须先接收该会话的所有事件
实时事件传输：应用内事件必须在对应会话结束后实时发送
顺序处理：会话顺序错误将导致数据不一致及归因错误

高级选项

扩展功能

Singular S2S集成支持需额外SESSION参数的高级功能

高级功能：请查阅高级S2S选项以满足深度链接、SKAdNetwork及跨设备追踪需求。

API 端点规范

SESSION 端点接受包含设备、应用及归因数据查询参数的 GET 请求。

端点 URL

基础URL与方法

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

请求格式：

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

请求正文：请勿提供请求正文——所有参数必须通过GET方法作为URL查询参数发送。

必填参数

所有 SESSION 请求必须包含以下必填参数，并确保其值与格式正确。

API认证

SDK密钥

参数类型描述

a

string

用于 API 认证的 Singular SDK 密钥。

获取路径：Singular UI → 主菜单 → 开发者工具

示例： sdkKey_afdadsf7asf56

重要提示：请勿使用报告 API密钥——请求将被拒绝。

设备标识符

平台专属标识符

设备标识符因平台及可用性而异。请包含您平台的所有适用标识符。

参数	平台	描述
`idfa`	iOS	广告商标识符 (IDFA) 支持广告追踪和营销活动归因。 ATT要求：iOS 14.5+系统需通过应用追踪透明框架获取用户主动授权若IDFA不可用（用户拒绝ATT提示）则省略该参数切勿传递NULL或空字符串获取IDFA 示例：`DFC5A647-9043-4699-B2A5-76F03A97064B`
`idfv`	iOS	供应商标识符（IDFV）在同一供应商的所有应用中保持一致。始终必需：无论ATT状态或IDFA可用性如何，都必须包含检索 IDFV 示例：`21DB6612-09B3-4ECC-84AC-B353B0AF1334`
`aifa`	Android (Google Play)	Google广告标识符（GAID）可在Android设备上实现用户可重置的广告追踪功能。 Google Play设备必备非Google Play设备可省略若不可用则省略——切勿传递NULL或空字符串获取AIFA 示例：`8ecd7512-2864-440c-93f3-a3cabe62525b`
`asid`	Android (Google Play)	Android应用集ID 为同一开发者的应用提供注重隐私的跨应用追踪功能。始终必需：必须包含在 Google Play设备上，无论GAID是否可用非Google Play设备可省略获取应用标识符示例：`edee92a2-7b2f-45f4-a509-840f170fc6d9`
`amid`	Android (Amazon)	Amazon广告ID 适用于未安装Google Play服务的亚马逊设备。亚马逊Fire设备必需若不可用则省略获取AMID 示例：`df07c7dc-cea7-4a89-b328-810ff5acb15d`
`oaid`	Android （中国制造商）	适用于未搭载Google Play服务的国产设备（华为、小米、OPPO等）的开放广告标识符（OAID）。适用于未安装Google Play服务的国产设备若不可用则省略获取OAID 示例：`01234567-89abc-defe-dcba-987654321012`
`andi`	Android (非Google Play)	Android ID 是设备生成的 64 位标识符。限制性使用：禁止在Google Play设备上使用——请改用AIFA和ASID。仅当无其他标识符可用且应用非通过Google Play分发时才发送。检索 ANDI 示例： `fc8d449516de0dfb`
`sdid`	PC、Xbox、PlayStation、Nintendo、MetaQuest、CTV	唯一设备标识符（SDI）是由客户端生成的UUIDv4，代表应用的唯一安装实例。主标识符：仅用于PC及主机应用的设备标识符示例：`40009df0-d618-4d81-9da1-cbb3337b8dec`
`sing`	仅限企业版	在标准标识符不可用时，用于特殊场景的客户端自定义标识符。受限：仅限企业客户使用需由Singular解决方案工程师按应用程序启用。详情请咨询客户成功经理。示例：`da534a95-1b1b-47d4-94b6-07955ec85177`

设备参数

设备信息

参数	描述
`p`	应用程序的平台。允许值（区分大小写）： Android iOS PC Xbox PlayStation 任天堂 MetaQuest CTV 示例： `Android`
`ip`	设备的公共IPv4地址。支持IPv6，但为确保与广告网络的归因兼容性，建议使用IPv4。示例： `172.58.29.235`
`ve`	设备在会话时的操作系统版本。示例： `9.2`
`ma` iOS、Android	设备品牌（制造商名称）。必须与`mo` （型号）配合使用。获取设备制造商示例： `Samsung`,`LG`, `Apple`
`mo` iOS, Android	设备型号。必须与`ma` （品牌）配合使用。检索设备型号示例： `iPhone 4S`, `Galaxy SIII`
`lc` iOS, Android	IETF区域设置标记——由下划线分隔的双字母语言代码和国家代码。检索设备区域设置示例： `en_US`
`bd` iOS、Android	设备构建标识符，URL编码格式。检索设备构建版本示例： `Build%2F13D15`

应用程序参数

应用程序信息

参数	描述
`i`	应用程序标识符（区分大小写）。 Android：包名（例如：`com.singular.app` ） iOS：包标识符（例如：`com.singular.app` ） PC/主机：您指定的标识符示例： `com.singular.app`
`app_v`	应用程序版本号。示例： `1.2.3`
`install`	表示会话是否为安装或重新安装后的首次会话。 `true` - 新安装/重新安装后的首次会话 `false` - 后续会话（应用已安装）必要条件：支持重新安装追踪功能示例： `true`
`install_time` iOS、Android	首次应用安装的Unix时间戳。示例： `1510040127`
`update_time` iOS、Android	应用最后更新的 Unix 时间戳。示例： `1510040127`
`att_authorization_status` iOS	应用追踪透明度（ATT）状态代码（iOS 14.5+）。状态值： `0` - 未确定（未显示提示） `1` - 受限（设备级跟踪已禁用） `2` - 拒绝（用户拒绝授权） `3` - 已授权（用户授予授权）始终要求：即使未实现ATT，也需传递`0` （未确定）。示例： `3`

欺诈预防参数

安装来源验证

参数描述

install_source
Android、PC

安装源包名称或商店标识符。

Android：安装源包名称

Android示例： com.android.vending (Google Play商店)

PC支持商店：

steam
epic
微软商店
humblestore
GOG
自主发行

install_receipt
iOS

用于欺诈验证的Base64编码iOS安装收据。

示例（截断）：MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

深度链接参数

深度链接支持

参数描述

openuri
iOS、Android

用于打开应用的URL编码深层链接、通用链接或应用链接。

原始网址：myapp://home/page?queryparam1=value1&queryparam2=value2

编码示例：myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2

ddl_enabled
iOS、Android

指示应用是否期望响应中包含延迟深层链接URL。

true - 响应中需包含延迟深层链接
false - 不期望延迟深层链接响应

示例响应：

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

singular_link_resolve_required
iOS, Android

请求将Singular短链接解析为长链接。必须配合openuri 使用，该URL需包含Singular短链接。

true - 返回展开后的完整链接
false - 不解析链接

示例响应：

{
  "status":"ok",
  "resolved_singular_link":"https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

高级归因参数

平台归因增强

参数描述

install_ref
Android（Google Play）
原生PC端（Google Play游戏）

JSON URL编码的Google安装来源信息。为Android和Google Play游戏PC端安装提供最精准的归因数据。

Android JSON结构：

{
   "installBeginTimestampSeconds":"1568939453",
   "referrer":"utm_source=google-play&utm_medium=organic",
   "clickTimestampSeconds":"0",
   "referrer_source":"service",
   "current_device_time":"1568944524"
}

原生PC JSON结构：

{
   "install_time_epoch_seconds":"1568939453",
   "install_referrer":"utm_source=google-play&utm_medium=organic"
}

适用对象：

Facebook用户级导出
数据目的地共享
回传准确性

更多信息：

URL编码示例：%7B%22installBeginTimestampSeconds%22%3A%221568939453%22...

meta_ref
Android (Google Play)

自2025年6月18日起：Meta高级移动测量（AMM）无需再实现Meta安装来源功能。启用AMM时不建议使用。

用于获取精细化用户级归因数据的 JSON URL编码Meta安装来源。

JSON结构：

{
  "install_referrer": {
    "utm_source":"apps.facebook.com",
    "utm_campaign": "fb4a",
    "utm_content": {
      "source":{
        "data":"c7e6b890bf18a059c2185650bdb1af3dced7...",
        "nonce":"24859720343e2381daee9f39ae61"
        },
      "app":533744218636280,
      "t":1731181327
      },
    "is_ct":1,
    "actual_timestamp":1731181444
  }
}

了解更多： Meta 引荐来源常见问题解答

attribution_token
iOS

通过AdServices框架获取Apple Search Ads归因令牌（iOS 14.3+）。

通过attributionToken() 方法获取 应用安装/重新安装后的首次启动时。

示例（截取）：KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP...

可选参数

可选参数可增强追踪能力并支持高级功能。

时间戳参数

参数描述

utime

10位数的Unix会话时间戳。

示例： 1483228800

umilisec

包含毫秒的13位Unix时间戳。

示例： 1483228800000

网络与位置参数

参数	描述
`use_ip`	指示Singular从HTTP请求中提取IP地址而非使用`ip` 参数。限制：阻止Singular基于IP地址的地理定位通过`country`参数提供两位字母国家代码与参数互斥——请勿同时使用与`ip` 参数互斥—— 不可同时使用必须提供`ip` 或`use_ip`参数以避免数据被拒绝示例： `true`
`country`	ISO 3166-1alpha-2 两位字母国家代码。适用场景：IP地址不可用或`use_ip=true`不可用示例： `US`
`ua`	URL编码的用户代理字符串。原始格式： `Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15...` 编码后： `Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0...`
`c` iOS, Android	网络连接类型。允许值： `wifi`, `carrier` 示例： `wifi`
`cn` iOS、Android	互联网服务提供商的运营商名称。示例： `Comcast`

自定义属性

参数描述

global_properties

URL编码的JSON对象，包含自定义键值对。

限制：

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

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

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

支持卸载追踪

参数描述

apns_token
iOS

十六进制编码的Apple推送通知服务(APNs)设备令牌。令牌。

iOS卸载跟踪必填项
必须为十六进制编码字符串
获取APNs令牌

示例： b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

fcm
Android

Firebase云消息服务设备令牌。

用于Android卸载跟踪
获取 FCM 令牌

示例： bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

数据隐私参数

参数描述

data_sharing_options

JSON URL编码的终端用户数据共享同意声明。必须在后续所有SESSION和EVENT请求中保持有效并传递。

用户同意（选择加入）：

{"limit_data_sharing":false}

用户拒绝（退出）：

{"limit_data_sharing":true}

URL编码示例： %7B%22limit_data_sharing%22%3Atrue%7D

dnt
iOS、Android

禁止追踪状态。

1 - 已启用不跟踪功能
0 - 禁用“禁止追踪”

示例： 0

dntoff
iOS、Android

指示是否关闭“禁止追踪”功能。

0 - 启用“禁止追踪”（OFF=false）
1 - 禁用“禁止追踪”（OFF=true）

示例： 1

跨设备支持

参数描述

custom_user_id

用于跨设备跟踪的内部用户ID。

示例： 123456789abcd

SKAdNetwork支持

参数描述

skan_conversion_value
iOS

会话时间点最新的SKAdNetwork转化值。

了解更多： SKAdNetwork 实现

示例： 7

skan_first_call_timestamp
iOS

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

示例： 1483228800

skan_last_call_timestamp
iOS

SKAdNetwork API 最近一次调用的 Unix 时间戳（按会话时间计算）。

示例： 1483228800

Google Ads ICM 支持（测试版）

参数描述

odm_info
iOS

Google Ads 集成转化测量（测试版）所需参数。

Google Ads ICM 文档

odm_error
iOS

Google Ads 整合式转化测量必备组件（测试版）。

Google Ads ICM 文档

请求示例

示例代码展示了跨多种编程语言的 SESSION 端点集成。

示例免责声明：代码示例可能未包含所有必需参数。在生产环境实施前请验证完整参数列表。开发/测试时请使用唯一的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',
    'aifa': '8ecd7512-2864-440c-93f3-a3cabe62525b',
    'asid': 'edee92a2-7b2f-45f4-a509-840f170fc6d9',
    'install': 'true',
    'n': 'MyCoolAppName',
    'bd': 'Build/13D15',
    'app_v': '1.2.3',
    'openuri': 'myapp://home/page?queryparam1=value1',
    'ddl_enabled': 'true',
    'install_source': 'com.android.vending',
    'install_time': 1510040127,
    'update_time': 1510090877
}

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

cURL 示例

curl -G "https://s2s.singular.net/api/v1/launch" \
  --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 "aifa=8ecd7512-2864-440c-93f3-a3cabe62525b" \
  --data-urlencode "asid=edee92a2-7b2f-45f4-a509-840f170fc6d9" \
  --data-urlencode "install=true" \
  --data-urlencode "n=MyCoolAppName" \
  --data-urlencode "bd=Build/13D15" \
  --data-urlencode "app_v=1.2.3" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1" \
  --data-urlencode "ddl_enabled=true" \
  --data-urlencode "install_source=com.android.vending" \
  --data-urlencode "install_time=1510040127" \
  --data-urlencode "update_time=1510090877"

HTTP示例

GET /api/v1/launch
    ?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
    &aifa=8ecd7512-2864-440c-93f3-a3cabe62525b
    &asid=edee92a2-7b2f-45f4-a509-840f170fc6d9
    &install=true
    &n=MyCoolAppName
    &bd=Build%2F13D15
    &app_v=1.2.3
    &openuri=myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1
    &ddl_enabled=true
    &install_source=com.android.vending
    &install_time=1510040127
    &update_time=1510090877 HTTP/1.1
Host: s2s.singular.net
Accept: application/json

Java示例

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

// 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("aifa", "8ecd7512-2864-440c-93f3-a3cabe62525b");
params.put("asid", "edee92a2-7b2f-45f4-a509-840f170fc6d9");
params.put("install", "true");
params.put("n", "MyCoolAppName");
params.put("bd", "Build/13D15");
params.put("app_v", "1.2.3");
params.put("openuri", "myapp://home/page?queryparam1=value1");
params.put("ddl_enabled", "true");
params.put("install_source", "com.android.vending");
params.put("install_time", "1510040127");
params.put("update_time", "1510090877");

// 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();

响应代码与错误

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

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

测试与验证

在生产部署前，使用 Singular SDK 控制台进行实时数据验证，验证 S2S 集成是否正确。

测试流程

端到端验证

注册测试设备：获取设备广告ID并添加至 Singular SDK控制台
启用控制台日志记录：在 SDK控制台添加设备标识符以捕获测试数据
使用开发版应用ID：覆盖应用标识符为开发版本（例如：com.singular.app.dev ）以隔离测试与生产数据
启动应用：从终止状态打开应用以触发会话
验证客户端数据：确认应用向服务器发送所有必需的 Singular数据点
验证服务器请求：确认服务器向https://s2s.singular.net/api/v1/launch发送包含所有必需参数的SESSION请求
检查SDK控制台：数秒内SESSION事件应出现在SDK控制台中
重复测试：验证每次应用启动及前台操作时是否触发SESSION事件

SDK Console Session Event

关键验证：确认应用开启/前台运行时在任何事件请求前触发SESSION事件。顺序错误将导致归因失误。

成功标志：若 SDK 控制台显示 SESSION 事件，则表示端到端集成测试已成功完成！

补充资源

测试文档

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

服务器到服务器 - 会话端点 API 参考

SESSION 端点 API 参考

概述

服务器到服务器用例

数据流架构

关键考量

会话管理

何时发送会话

会话触发条件

会话超时逻辑

归因处理

基于会话的归因

事件顺序要求

高级选项

扩展功能

API 端点规范

端点 URL

基础URL与方法

必填参数

API认证

SDK密钥

设备标识符

平台专属标识符

设备参数

设备信息

应用程序参数

应用程序信息

欺诈预防参数

安装来源验证

深度链接参数

深度链接支持

高级归因参数

平台归因增强

可选参数

时间戳参数

网络与位置参数

自定义属性

支持卸载追踪

数据隐私参数

跨设备支持

SKAdNetwork支持

Google Ads ICM 支持（测试版）

请求示例

Python示例

cURL 示例

HTTP示例

Java示例

响应代码与错误

测试与验证

测试流程

端到端验证

补充资源

测试文档