SESSION 端点 API 参考

通过 Singular 的 REST API 使用服务器到服务器集成作为 SDK 实现的替代方案，追踪用户会话并为应用安装、再互动和留存指标启用归因。

概述

服务器到服务器用例

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

支持的功能：

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

数据流架构

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

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

会话数据流示意图

关键注意事项

关键要求：

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

集成优势：

灵活性： 完全掌控数据收集和传输时机
功能对等： 在提供适当数据的情况下支持所有 SDK 功能
自定义实现： 根据特定的后端架构调整集成

会话管理

SESSION 端点向 Singular 通知应用打开事件，以初始化用户会话进行归因和追踪。

何时发送会话

会话触发条件

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

全新安装： 安装后首次启动应用
从终止状态启动： 应用从完全关闭状态打开
从后台切换到前台： 应用在超时时间后返回前台（推荐：60 秒）

会话超时逻辑

实现会话超时以防止在应用短暂进入后台期间产生过多的 SESSION 请求。

推荐实现：

超时时长： 60 秒（1 分钟）
前台时间 < 超时时间： 如果应用在超时时间内返回前台，则不发送 SESSION
前台时间 > 超时时间： 如果应用在后台停留超过超时时间，则发送 SESSION
应用生命周期追踪： 使用应用生命周期事件和计时器来管理会话状态

深度链接支持： 对于通过深度链接、Universal Links 或 App Links 打开且填充了 openuri 参数的应用打开，无论超时状态如何，都始终发送 SESSION。

归因处理

基于会话的归因

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

会话类型	Singular 处理	归因结果
首次会话（新安装）	触发安装归因流程	将安装归因到营销活动
符合再互动条件	触发再互动归因流程	将用户回访归因到营销活动或深度链接
标准会话	记录会话以进行留存追踪	计入用户活动和互动指标

了解更多：再互动归因常见问题

事件顺序要求

会话和事件的时机直接影响归因准确性和数据质量。

关键顺序规则：

会话先于事件： 在该会话的任何事件之前，必须先接收到单个 SESSION
实时事件传输： 应用内事件必须在各自的会话之后实时发送
顺序处理： 无效的会话顺序会导致数据不一致和归因错误

高级选项

扩展功能

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 Key

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

设备标识符

平台特定标识符

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

设备参数

设备信息

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

应用程序参数

应用信息

应用标识符（ i ）、 app_v 和 att_authorization_status 是共享参数。请参阅 S2S 基础知识中的应用程序参数。

参数详情


        install

boolean

指示会话是否代表安装或重新安装后的首次会话。

true - 全新安装/重新安装后的首次会话
false - 后续会话（应用已安装）

需要用于： 重新安装追踪功能

示例： true


        install_time

iOS, Android

integer

首次应用安装的 Unix 时间戳。

示例： 1510040127


        update_time

iOS, Android

integer

最后一次应用更新的 Unix 时间戳。

示例： 1510040127

反欺诈参数

安装来源验证

参数详情


        install_source

Android, PC

string

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

Android: 安装来源包名

Android 示例： com.android.vending （Google Play Store）

PC 支持的商店：

steam
epic
microsoftstore
humblestore
gog
selfdistributed


        install_receipt

iOS

string

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

示例（截断）： MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1m...

深度链接参数

深度链接支持

参数详情


        openuri

iOS, Android

string

打开应用的 URL 编码深度链接、Universal Link 或 App Link。

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

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


        ddl_enabled

iOS, Android

boolean

指示应用是否期望在响应中收到延迟深度链接 URL。

true - 期望在响应中收到延迟深度链接
false - 不期望收到延迟深度链接

响应示例：

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


        singular_link_resolve_required

iOS, Android

boolean

请求将 Singular 短链接解析为长链接。必须与包含 Singular 短链接的 openuri 一起使用。

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)
Native PC (Google Play Games)

JSON

JSON URL 编码的 Google Install Referrer 信息。为 Android 和 Google Play Games PC 安装提供最准确的归因。

Android JSON 结构：

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

Native PC JSON 结构：

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

需要用于：

Facebook 用户级导出
Data Destination 共享
Postback 准确性

更多信息：

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


        meta_ref

Android (Google Play)

JSON

自 2025 年 6 月 18 日起： Meta Advanced Mobile Measurement (AMM) 无需再实现 Meta Install Referrer。如果已启用 AMM，则不推荐使用。

JSON URL 编码的 Meta Install Referrer，用于获取精细的用户级归因数据。

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 Referrer 常见问题


        attribution_token

iOS

string

来自 AdServices 框架的 Apple Search Ads 归因令牌（iOS 14.3+）。

检索方式： 在安装/重新安装后首次启动应用时使用 attributionToken() 。

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

可选参数

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

时间戳参数

参数详情


        utime

integer

会话的 10 位 Unix 时间戳。

示例： 1483228800


        umilisec

integer

带毫秒的 13 位 Unix 时间戳。

示例： 1483228800000

网络和位置参数

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

自定义属性

参数详情


        global_properties

JSON

带有自定义键值对的 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

string

十六进制编码的 Apple Push Notification Service (APNs) 设备令牌。

iOS 卸载追踪所需
必须是十六进制编码字符串
检索 APNs 令牌

示例： b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052

fcm

Android

string

Firebase Cloud Messaging 设备令牌。

Android 卸载追踪所需
检索 FCM 令牌

示例： bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1

数据隐私参数

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

跨设备支持

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

SKAdNetwork 支持

参数详情


        skan_conversion_value

iOS

integer

会话时的最新 SKAdNetwork 转化值。

了解更多： SKAdNetwork 实现

示例： 7


        skan_first_call_timestamp

iOS

integer

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

示例： 1483228800


        skan_last_call_timestamp

iOS

integer

会话时最近一次调用 SKAdNetwork API 的 Unix 时间戳。

示例： 1483228800

Google Ads ICM 支持（Beta）

参数详情


        odm_info

iOS

string

Google Ads Integrated Conversion Measurement (Beta) 所需。

Google Ads ICM 文档


        odm_error

iOS

string

Google Ads Integrated Conversion Measurement (Beta) 所需。

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 Console 进行实时数据验证以验证 S2S 集成。

测试步骤

端到端验证

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

SDK Console 会话事件

关键验证： 确认 SESSION 事件在任何 EVENT 请求之前于应用打开/进入前台时发生。无效的顺序会导致归因错误。

成功标志： 如果 SESSION 出现在 SDK Console 中，则说明您已完成成功的端到端集成测试！

其他资源

测试文档

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

服务器到服务器 - SESSION 端点 API 参考

SESSION 端点 API 参考

概述

服务器到服务器用例

数据流架构

关键注意事项

会话管理

何时发送会话

会话触发条件

会话超时逻辑

归因处理

基于会话的归因

事件顺序要求

高级选项

扩展功能

API 端点规范

端点 URL

基础 URL 和方法

必需参数

API 身份验证

SDK Key

设备标识符

平台特定标识符

设备参数

设备信息

应用程序参数

应用信息

反欺诈参数

安装来源验证

深度链接参数

深度链接支持

高级归因参数

平台归因增强

可选参数

时间戳参数

网络和位置参数

自定义属性

卸载追踪支持

数据隐私参数

跨设备支持

SKAdNetwork 支持

Google Ads ICM 支持（Beta）

请求示例

Python 示例

cURL 示例

HTTP 示例

Java 示例

响应代码和错误

测试和验证

测试步骤

端到端验证

其他资源

测试文档