SESSION 端点 API 参考

关注
Avatar
Jared Ornstead
Updated

SESSION 端点 API 参考

服务器到服务器用例

作为 SDK 的替代方案，Singular REST API 可实现服务器到服务器的直接集成。LAUNCH 或会话端点可在应用程序中实现会话跟踪。当您的应用程序将特定于设备的数据转发给您的服务器时，服务器会将数据传输到 Singular 的服务器，然后 Singular 平台会对这些信息进行处理，以实现以下目的：安装归因、再参与归因和保留指标。这些经过处理的数据会自动填充到您的报告、导出日志和配置的回传中，为您的营销活动提供全面的分析。

SDK 会自动收集设备和应用程序数据，而 S2S 方法则要求您： 1：

  1. 从您的应用程序中收集所需的数据点
  2. 将这些数据转发到您的服务器
  3. 通过 REST API 发送给 Singular
  4. 将 Singular 的响应传回应用程序

session-data-flow.png

关键点

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

会话管理

LAUNCH 端点用于通知 Singular 一个新用户会话的应用程序打开事件。

  • 以下情况需要会话初始化（启动请求
    • 新安装的应用程序
    • 应用程序从终止状态启动
    • 应用程序从后台返回前台
  • 会话必须在任何事件跟踪之前建立
  • 无效的会话顺序会导致数据不一致
  • 建议实施会话超时，只有在过去 1 分钟内未使用应用程序时才向 Singular 发送会话通知。如果用户进入应用程序后台，然后在 1 分钟或更短时间内前景化应用程序，则不应触发会话，但如果用户在超过 1 分钟的时间内前景化应用程序，则应触发会话。
  • 为了支持深度链接，在打开应用程序时，必须始终通过 "open_uri "参数中的 openURL 发送会话。

开始使用

会话端点文档提供了以下内容：

请务必查看 Singular 服务器到服务器（S2S）集成的高级选项，这些选项要求会话通知端点包含附加参数。点击此处了解高级选项。

报告会话

与 Singular 的最基本集成包括在发生用户会话时通知 Singular，允许 Singular 触发多个内部流程：

  • 如果这是应用程序在特定设备上的首次会话，Singular 会识别为新安装并触发安装归因流程。
  • 如果会话符合重新参与会话的条件，Singular 会触发重新参与归因流程（在重新参与常见问题中了解更多信息）。
  • 否则，Singular 会将其标记为会话，用于跟踪用户活动和保留指标。

向 Singular 服务器发出会话请求和后续事件请求的时机至关重要：

  1. 在发生任何事件之前，必须先收到一个会话。
    例如，当用户开始使用应用程序时，Singular SDK 会在应用程序打开时触发会话，然后在会话后发送应用程序内事件。如果用户将应用置于后台的时间较长（超过 1 分钟），会话就会超时。当应用程序回到前台时，将发送另一个会话。建议使用应用程序生命周期事件和计时器来帮助管理会话，并调节对 Singular 的会话请求。
  2. 应用程序中发生的事件必须在各自会话结束后实时发送。

会话 API 端点

HTTP 方法和会话端点

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

所需参数

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

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

 

  • 所有必填参数都必须包含在会话 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 分配给设备的唯一标识符，专门针对特定供应商或开发者。该标识符在特定设备上来自同一供应商的所有应用程序中保持一致，允许供应商在其应用程序生态系统中跟踪用户行为和交互，而无需识别用户个人身份。

 

示例值： 
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。该值是客户端生成的 UUIDv4，代表唯一的应用程序安装。这是 PC 和控制台应用程序使用的唯一设备标识符。

 

示例值： 
40009df0-d618-4d81-9da1-cbb3337b8dec
参数 说明 
sing

支持的平台：

  • 仅限特殊用例
  • 更多信息，请联系您的解决方案工程师或 CSM
 
string

sing参数仅限企业客户使用，用于指定客户端定义的标识符。仅用于无法使用所有其他标识符的特殊用途。该标识符必须由 Singular 解决方案工程师逐个应用程序启用。

 

示例值： 
da534a95-1b1b-47d4-94b6-07955ec85177
设备参数
参数 说明 
p
 
string

p参数指定应用程序的平台。

下面列出了允许使用的区分大小写的 参数值：

  • 安卓
  • iOS
  • 个人电脑
  • Xbox
  • 游戏机
  • 任天堂
  • 元探索
  • 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
  • 您为 PC、Xbox、Playstation、任天堂、MetaQuest 或 CTV 指定的标识符

 

示例值： 
com.singular.app
参数 说明 
app_v
 
string

app_v参数指定应用程序版本。

 

示例 
1.2.3
参数 说明 
install
 
string

install参数指定此会话是否为安装或重新安装后的第一个会话。如果会话是安装应用后的第一个会话，则传入"true"；如果应用已安装，且这是后续会话或应用打开，则传入"false"。重新安装跟踪功能需要此参数。

 

示例 
true
参数 描述 
install_time

支持的平台：

  • 安卓
  • iOS
 
int

install_time参数指定首次安装应用程序的时间（UNIX 时间）。要检索此值，请使用平台上的链接。

 

示例值： 
1510040127
参数 说明 
update_time

支持的平台：

  • 安卓
  • iOS
 
int

update_time参数指定上次应用更新的时间（UNIX 时间）。要检索该值，请使用平台上的链接。

 

示例值： 
1510040127
参数 说明 
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
欺诈参数
参数 描述 
install_source

支持的平台：

  • 安卓
  • 电脑
 
string

install_source参数指定 Android 上的安装源软件包名称。PC 上安装源的推荐值是安装商店。

支持的 PC 安装商店名称包括

  • 蒸汽
  • 史诗
  • microsoftstore
  • humblestore
  • gog
  • 自行发布

 

Android 示例（Google Play 商店）：

com.vending.android
参数 说明 
install_receipt

支持的平台：

  • iOS
 
string

install_receipt参数指定从安装中收到的收据。了解如何在 iOS 安装收据中获取收据

 

来自 iOS 的 base64 编码收据字符串示例： 
MIJF9wYJKoZIhvcNAQcCoIJF6DCCReQCAQExCzAJBgUrDgMCGgUAMII1mAYJKoZIhvcNAQcBoII1iQSCNYUxgjWBMAoCAQgCAQEEAhYAMAoCARQCAQEEAgwAMAsCAQECAQEEAwIBADALAgELAgEBBAMCAQAwCwIBDwIBAQQDAgEAMAsCARACAQEEAwIBADALAgEZAgEBBAMCAQMwDAIBAwIBAQQEDAIyNTAMAgEKAgEBBAQWAjQrMAwCAQ4CAQEEBAICAM8wDQIBDQIBAQQFAgMCIuAwDQIBEwIBAQQFDAMxLjAwDgIBCQIBAQQGAgRQMjU1
深度链接参数
参数 说明 
openuri

支持的平台：

  • 安卓
  • iOS
 
URL-encoded string

openuri参数用于指定应用是通过任何深度链接、iOS 通用链接还是 Android 应用链接打开的，您应提供 URL 编码的打开 URL 值。

打开 URL： 
myapp://home/page?queryparam1=value1&queryparam2=value2

 

示例值： 
myapp%3A%2F%2Fhome%2Fpage%3Fqueryparam1%3Dvalue1%26queryparam2%3Dvalue2
参数 说明 
ddl_enabled

支持的平台：

  • 安卓
  • iOS
 
string

ddl_enabled参数用于指定应用程序是否支持延迟深度链接。如果服务器希望返回延迟深度链接 URL，则输入"true"，否则输入"false"。

 

示例值： 
true

 

示例响应： 
{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}
参数 描述 
singular_link_resolve_required

支持的平台：

  • 安卓
  • iOS
 
string

singular_link_resolve_required参数用于解析奇异短链接。发送时必须在 "openuri "中包含奇异短链接的值。如果服务器希望返回扩展的短链接（长链接），则传入"true"，否则传入"false"。请参阅短链接处理。

 

示例值： 
true

 

示例响应： 
{
  "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

支持的平台：

  • 安卓
    (谷歌播放设备）
 
JSON URL-encoded string

install_ref参数用于指定 Google 安装推荐人信息。安装推荐人信息包含将用户发送到 Google Play 商店的相关信息。如果 Singular 可以使用安装推荐人信息，它就能提供最准确的安装属性。在第一次会话通知调用时读取此值并将其传递给 Singular。

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

一些重要的 Singular 功能都需要它，例如在用户级导出（User-Level Exports）中接收 Facebook 数据、与数据目的地（Data Destinations）共享数据以及发送回帖。

Google Play 会在用户访问商店时收集推荐人信息。如果用户后来安装了他们被引导到的应用程序，Google Play 就会向该应用程序提供这些信息。更多信息，请参阅Google 开发者文档。

 

示例值： 
%7B%22installBeginTimestampSeconds%22%3A%221568939453%22%2C%22referrer%22%3A%22utm_source%3Dgoogle-play%26amp%3Butm_medium%3Dorganic%22%2C%22clickTimestampSeconds%22%3A%220%22%2C%22referrer_source%22%3A%22service%22%2C%22current_device_time%22%3A%221568944524%22%7D
参数 说明 
meta_ref

支持的平台：

  • 安卓
    (谷歌播放设备）
 
JSON URL-encoded string

meta_ref参数指定了 "Meta Referrer"，这是 Facebook 推出的 Android 专用测量解决方案，允许广告商访问 Android 应用程序安装的细粒度用户级归因数据（请参阅Facebook 的数据政策）。它由实施 "Google Play 安装推荐人"（请参阅 "传递 Google 安装推荐人"）和 "元安装推荐人 "技术组成，用于测量应用程序的安装情况。请在常见问题解答中阅读有关Meta Referrer 的更多信息。

{
  "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,
  }
}

 

示例值： 
%7B%22install_referrer%22%3A%7B%22utm_source%22%3A%22apps.facebook.com%22%2C%22utm_campaign%22%3A%22fb4a%22%2C%22utm_content%22%3A%7B%22source%22%3A%7B%22data%22%3A%22c7e6b890bf18a059c2185650bdb1af3dced7...%22%2C%22nonce%22%3A%2224859720343e2381daee9f39ae61%22%7D%2C%22app%22%3A533744218636280%2C%22t%22%3A1731181327%7D%2C%22is_ct%22%3A1%2C%22actual_timestamp%22%3A1731181444%2C%7D%7D
参数 说明 
attribution_token

支持的平台：

  • iOS
 
string

attribution_token参数指定在 iOS 14.3+ 上通过 AdServices 框架检索的 Apple Search Ads 归因令牌。

在安装或重新安装后首次初始化应用程序时，立即使用attributionToken()提取归因令牌。

 

示例值： 
KztLg%2FIkNsWDMuBMOU%2BySnkPU5myJb4OFmeaMUE%2BTqQJP1HWL%2FBdpQKNHSnghf0uQpWDsdNcoWHHlXzrRta22Aww4QsUdPGKLwAAAVADAAAAwgAAAIAOMB3LOGJVmcso4G42C3bF8API7suoQgqrM9xfbMKtjpn0anD4Xca2Ma8fMa%2FZLBqWalHYmm58zs4bH1XUDtBcSex1d80D4AhnnPoSYFukr%2ACfLCEnT2lHurPb5cPPQ17ewCd3ctuuZYGHuvV66AkU1ExJUguciTXTNEgY%2Fc19rQAAAB%2BF8udKcAQxkREhEtyGQGRUFydziffiLHBN7bXKSHPFAAAAnwGYh9H%2BPP4rEQGnbnTiQUnkfqgfKQAAAIYCCLjE6nnxqwDQPb4%2FF0Wve%2FVnSwwUxYGsi2a3V5dioUgCzty2kAG8kUsNjk0rU0Z0UrOhvCR%2FGfLXQv7HsMIZlbeKoHast6%2BXfiFsA2x244gztybPDecoGAvsmOeBKxjJqPDGqYxIpBgGaggGg1wonia%2BhxqjcLpEKG%2F%2F%2FEOZb3Jdf%2FaN%2FQABBEkLAAA%3D

请求正文

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

 

请求示例

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

 

PYTHON CURL HTTP JAVA

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

 

可选参数

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

可选参数
时间戳参数
参数 说明 
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
参数 说明 
ua
 
URL-encoded string

ua参数指定设备的用户代理。

Mozilla/5.0 (iPhone; CPU iPhone OS 14_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148

该值必须是 URL 编码。

 

示例值

Mozilla%2F5.0%20(iPhone%3B%20CPU%20iPhone%20OS%2014_0%20like%20Mac%20OS%20X)%20AppleWebKit%2F605.1.15%20(KHTML%2C%20like%20Gecko)%20Mobile%2F15E148
参数 说明 
c

支持的平台：

  • iOS
  • 安卓
 
string

c参数指定网络连接类型"wifi"或"运营商"。

 

示例值：

wifi
参数 说明 
cn

支持的平台：

  • iOS
  • 安卓
 
string

cn参数指定互联网提供商的运营商名称。

 

示例值：

Comcast
卸载跟踪支持
参数 说明 
apns_token

支持的平台：

  • iOS
 
string

apns_token参数指定 Apple 推送通知服务 (APNS) 设备令牌。

    • 为 iOS 卸载跟踪所必需
    • 确保以十六进制编码字符串的形式传递 APNS 令牌
    • 如何检索 APNS 令牌

 

示例值：

b0adf7c9730763f88e1a048e28c68a9f806ed032fb522debff5bfba010a9b052
参数 说明 
fcm

支持的平台：

  • 安卓
 
string

fcm参数指定 Firebase Cloud Messaging 设备令牌。

  • 安卓卸载跟踪需要
  • 如何获取 FCM 令牌
    • 然后在向 Singular 报告会话时，在 fcm 参数中传递设备令牌，如下例所示：

 

示例值：

bk3RNwTe3H0CI2k_HHwgIpoDKCIZvvD...MExUdFQ3P1
数据隐私
参数 说明 
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
参数 说明 
dnt

支持的平台：

  • 安卓
  • iOS
 
int

dnt参数指定 "请勿追踪 "的状态。如果启用了 "不跟踪"，则传递1；如果禁用了 "不跟踪"，则传递0。

 

示例值： 
0
参数 说明 
dntoff

支持的平台：

  • iOS
  • 安卓
 
int

dntoff参数用于指定是否关闭 "不跟踪 "功能。如果启用 "不跟踪"，则输入0；如果禁用 "不跟踪"，则输入1。

 

示例值： 
1
跨设备支持
参数 说明 
custom_user_id
 
string

custom_user_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 是否接收到数据。详情请参考我们的测试指南。一般来说，应遵循以下步骤：

  1. 获取测试设备的广告 ID，并在 Singular SDK 控制台中添加该 ID。
  2. 打开 Singular SDK 控制台，添加设备标识符以开始捕获数据。
  3. 用开发应用程序标识符（com.singular.app.dev）覆盖应用程序标识符，将测试数据和事件与生产数据分开。
  4. 从终止状态构建或打开应用程序
  5. 验证 "应用程序打开 "与所有必要的 Singular 数据点一起发送到服务器
  6. 验证服务器会触发会话通知到 Singular 的"启动"端点，并包含所有必要的数据点。
  7. 几秒钟后，Singular SDK 控制台中将显示会话事件。
    s2s_session.png
  8. 重复测试，验证应用程序打开是否会触发每个应用程序入口或 "前台 "操作的会话。
重要验证

确认会话事件发生在 "应用程序打开 "或 "前台 "操作中，且在收到事件之前。

如果在 SDK 控制台中看到会话，则表示已完成会话处理的端到端测试！