# Singular 集成方案
TIP
请注意，第三方数据集成产生的数据会被纳入集群的消耗数据量
# 概要
# 接口简介
| 接口名 | 类型 | 粒度 | 归因 | 成本 | 收益 | 展示 | 点击 | 转化 |
|---|---|---|---|---|---|---|---|---|
| Internal BI Postbacks | 回传 | 用户级别 | ✅ | ✅ | ✅ |
Singular 提供了合作伙伴设置回调功能 (opens new window)，您可以使用该功能回传用户粒度数据，包括归因数据、广告收益以及转化数据
在开始接入 Singular 数据前，请确保您已经阅读 TE 系统用户识别规则，理解 TE 如何通过 #distinct_id 和 #account_id 识别一个用户
# 集成流程
- 接入 Singular 客户端 SDK 与 TE 客户端 SDK，在 Singular SDK 中设置 TE 用户识别 ID
- 登录 TE 后台，进入三方集成模块，新增 Singular 回传方案，完成相关配置并获取回调地址
- 在 Singular 的后台添加 Internal BI 回调
- 查看 TE 系统否成功接收数据，并完成报表搭建
# 一、客户端 SDK 配置
如果要将 Singular 的回传数据与 TE 项目的用户数据进行打通，就需要在 Singular SDK 中上报 TE 项目的账号 ID 与访客 ID。
我们非常建议您先初始化 TE SDK，并在 Singular SDK 初始化时将 TE SDK 的访客 ID 设置为 Singular 的自定义用户 ID，以下是 Android 的代码样例：
// 初始化 TE SDK
ThinkingAnalyticsSDK instance = ThinkingAnalyticsSDK.sharedInstance(this, TA_APP_ID, TA_SERVER_URL);
// 获取 TE 的访客 ID, 对应 TE 中的 #distinct_id
String te_distinct_id = ThinkingAnalyticsAPI.GetDistinctId();
// 在 SingularConfig 中传入 TE 的访客 ID, 将其作为自定义用户 ID，并进行初始化
SingularConfig config = new SingularConfig("SDK KEY","SDK SECRET")
.withCustomUserId(te_distinct_id);
Singular.init(context, config);
# 二、方案配置
完成 SDK 配置后，接下来需要您登录 TE 系统后台，在「三方集成」模块中完成 Singular 方案的配置。下图是 Singular Internal BI Postbacks 方案的配置界面：
# 2.1 用户识别字段
由于 Singular Internal BI Postbacks 数据是用户级别数据，因此需要为其设置用户识别规则，即 Singular SDK 中设置的 TE 系统的用户识别 ID。TE 系统将根据该配置，在转换回传数据时，将这些字段设置为数据中的用户识别字段。
如果您按照本文档上一步进行客户端 SDK 配置，请使用以下配置：
- 账号 ID 关联字段：无
- 访客 ID 关联字段：user_id
# 2.2 事件表入库设置
打开「事件表入库设置」开关后，Singular 回传的数据都将写入到事件表中，我们建议您开启事件数据入库。 
# 2.3 用户属性入库规则
在默认情况下，TE 系统不会将 Singular 数据写入到用户属性中。如果您希望将一些字段写入用户表，比如用户归因信息字段，请首先打开规则，使其运行，再通过属性映射功能添加需要写入用户表的字段，来源属性名需填写字段的入库名：
我们建议您可以按照以下方式设置用户属性入库规则：
- 关闭「包含所有事件」
- 来源事件名选择：singular_install
- 入库规则使用：user_setOnce
- 属性字段配置如下：
| 来源数据名 | 目标属性名 | 说明 |
|---|---|---|
| network | te_ads_object.media_source | 媒体渠道 |
| tracker_campaign_name | te_ads_object.campaign_name | 广告计划名 |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 广告组名 |
| tracker_creative_name | te_ads_object.ad_name | 广告名 |
# 2.4 集成配置
您可以在集成配置模块对数据拉取的细节配置进行控制。比如入库后的事件名等
集成配置中的内容是一个 JSON，您可以按照以下内容进行自定义配置：
| 模块 | 名称 | 含义 |
|---|---|---|
| sink_event | event_mapping | 入库后的事件名，可以自定义。Key 为 Singular 回传数据的事件名，Value 为该事件入库后的事件名。如果有事件没有写在此处，则会按照回传数据的事件名在前加 singular_ 前缀作为其入库事件名 |
# 2.5 终端地址
终端地址中展示了 TE 系统接收 Singular 回传数据的地址。请您直接复制该地址，在接下来进行 Singular 回传配置时，请将该地址填入：
若此处无地址没有显示，请进入右上角菜单「项目管理」-「接入配置」-「数据上报地址」处配置公网地址。该地址即 TE SDK 中配置的数据上报地址。配置后再回到 Singular 配置页的「数据源」复制终端地址。
最后，别忘了点击右上角的保存按钮，将 Singular 方案保存下来。
# 三、配置回调与数据入库
# 3.1 配置回调
当您创建完成了 Singular 的方案，登录 Singular 后台，进入 Attribution > Partner Configuration 页，点击「Add a Partners」，在搜索框内输入 Internal BI 并点击，即可添加一个 Partner Configuration。
进入 Configuration 页面，首先选择需要回传数据的 App 和 Site
其次，请将 TE 系统中 Singular 集成方案的回调地址，填入 Postback URL 中
最后，Singular 的会默认回传安装事件（install），如果您还有应用内事件需要回传，请在下拉框中选择「Send all events, regardless of attributed partner」，并在其下方添加需要回传的事件（如果是收益事件，可以勾选收益数据回传）：
WARNING
注意：SDK事件列表中包括以下几种收益事件选项：
- __IAP__是指所有没有自定义名称的应用内购买事件
- 直接显示事件名的收益事件指的是已经经过重命名的应用内购买事件
- ADMON_USER_LEVEL_REVENUE 指的是广告收益事件（如果您配置了 Ad Revenue Attribution）
- __REVENUE__包括:
- 所有应用内购买事件（包含__IAP__与自定义的应用内购买事件）
- 广告收益事件（如果您配置了 Ad Revenue Attribution）
- 并且会将所有收益数据统一成一个事件进行回传
在配置回传时，请确认应用内购买事件是否在 TE SDK 中已经上报了。如果 TE SDK 中已上报应用内购买事件，则不建议您从 Singular 回传__IAP__以及其他应用内购买事件，避免数据重复 另外，由于__REVENUE__会将所有收益事件统一成一个事件，因此如果您的项目中同时记录了应用内购买事件以及广告收益事件，则不建议配置__REVENUE__，而是单独配置每一个收益事件，从而更好地内购与广告变现数据
# 3.2 事件入库规则
- 使用数据中的 user_id 字段，作为用户的访客 ID
- 使用数据中的 event_utc_timestamp 字段，即事件发生时间，作为数据的 #event_time
- 数据事件名取数据中的 event_name，并加前缀 singular_ ，未命名的收益事件将会被命名为：
- IAP：singular_iap
- ADMON USER_LEVEL_REVENUE_：singular_ad_revenue
- REVENUE：singular_revenue
- 其余字段都将会入库，以下展示的是 Internal BI Postbacks 回传的字段：
| 字段 | 含义 |
|---|---|
| app_name | 应用名称 |
| longname | 应用的 bundle ID |
| platform | 操作系统，取值为 iOS 或 Android |
| event_name | 事件名称 |
| idfa | iOS 的 IDFA |
| idfv | iOS 的 IDFV |
| aifa | Android 设备的广告标识 ID |
| android_id | Android ID，只有 AIFA 不可用时才会上报 |
| singular_id | （过时）当 iOS 设备限制数据跟踪（开启 LAT 时）才会上报，使用Singular 内部 ID |
| event_utc_timestamp | 事件发生时的 UNIX 时间戳 |
| click_utc_timestamp | 点击时的 UNIX 时间戳 |
| install_utc_timestamp | 安装时的 UNIX 时间戳 |
| is_organic | 1 代表用户是自然量，0 代表用户是非自然量 |
| is_viewthrough | 1 代表用户是展示归因，0 则反之 |
| network | 用户归因的媒体渠道 |
| campaign | Singular 标识的 Campaign 名 |
| campaign_group | Singular 标识的 Campaign 组名（部分平台会有） |
| creative | Singular 标识的创意名或创意 ID |
| site | Source site & Sub Site for click. Available if passed in click |
| user_id | 自定义用户 ID，根据 2.1 的配置，值应等于 TE 系统访客 ID |
| singular_click_id | Singular 生成的唯一点击 ID |
| is_reengagement | 1 代表再营销广告回流用户，0 则相反 |
| click_ip | 点击广告时的 IP 地址 |
| os_version | 点击广告时的操作系统版本 |
| app_version | 安装或事件发生时的应用版本 |
| country | 用户安装时的国家（地区） |
| city | 用户安装时的城市 |
| limit_ad_tracking | 1 代表开启了限制追踪，0 代表其他情况 |
| device_model | 设备机型 |
| device_brand | 设备品牌 |
| match_type | 归因匹配模式，取值有 deterministic (设备 ID 匹配，精准匹配), probabilistic (Android 独有，模糊匹配), or none (即自然量). |
| amount | 收益数据才会回传，以美元计价的收益值 |
| currency | 收益数据才会回传，收益计价币种的 ISO 4217 三位字母的货币代码 |
| is_first_event | 1 代表该事件（收益或自定义事件）是该设备第一个时间，0 代表不是第一个事件 |
| tracker_campaign_name | 渠道回传的 Campaign 名 |
| tracker_campaign_id | 渠道回传的 Campaign ID |
| tracker_sub_campaign_name | 渠道回传的 Sub-campaign 名 |
| tracker_sub_campaign_id | 渠道回传的 Sub-campaign ID |
| tracker_creative_name | 渠道回传的创意名 |
| tracker_creative_id | 渠道回传的创意 ID |
| tracker_publisher_id | 渠道回传的哈希后的 App ID |
| tracker_publisher_sub_id | 渠道回传的 Publisher SUB ID |
| tracker_publisher_site_name | 渠道回传的 App 名 |
| tracker_publisher_site_id | 渠道回传的 App ID |
| tracker_publisher_sub_site_name | 渠道回传的 Sub-publisher 名 |
| tracker_publisher_sub_site_id | 渠道回传的 Sub-publisher ID |
| tracker_name | 追踪到的 Campaign 名 |
| network_tiktok_restricted | 对于 Tiktok 的展示归因用户数据，会有该限制字段，详见附录 |
| campaign_tiktok_restricted | 对于 Tiktok 的展示归因用户数据，会有该限制字段，详见附录 |
| fb_campaign_id | Facebook 的 Campaign ID，会收到 Facebook 服务条款的限制，详见附录 |
| fb_campaign_name | Facebook 的 Campaign 名，会收到 Facebook 服务条款的限制，详见附录 |
| fb_adset_id | Facebook 的 Ad Set（广告组）ID，会收到 Facebook 服务条款的限制，详见附录 |
| fb_adset_name | Facebook 的 Ad Set（广告组）名，会收到 Facebook 服务条款的限制，详见附录 |
| fb_ad_id | Facebook 的广告 ID，会收到 Facebook 服务条款的限制，详见附录 |
| fb_ad_name | Facebook 的广告名，会收到 Facebook 服务条款的限制，详见附录 |
| twitter_campaign_name | Twitter 的 Campaign 名，会收到 Twitter 服务条款的限制，详见附录 |
| twitter_campaign_id | Twitter 的 Campaign ID，会收到 Twitter 服务条款的限制，详见附录 |
| twitter_line_id | Twitter 的 Line Item（广告组） ID，会收到 Twitter 服务条款的限制，详见附录 |
| fraud_status | 假量识别的结果，只有开启 fraud postbacks 时才会回传，取值为"valid"/"suspicious"/"rejected"（有效/疑似/拒绝） |
| fraud_reason | 假量数据的识别规则名，只有开启 fraud postbacks 时才会回传 |
# 3.3 标准化字段
Singular 回调数据中的部分字段，TE 系统会进行标准化处理：
| 字段 | 标准化字段 | 含义 |
|---|---|---|
| app_name | te_ads_object.app_name | 应用名 |
| longname | te_ads_object.app_id | 应用 ID |
| platform | te_ads_object.platform | 平台，即 Android、iOS 等 |
| country | te_ads_object.country | 国家地区编码 |
| amount | te_ads_object.revenue | 变现收益 |
| currency | te_ads_object.currency | 收益的币种 |
| network | te_ads_object.media_source | 媒体渠道 |
| tracker_campaign_name | te_ads_object.campaign_name | 广告计划名 |
| tracker_campaign_id | te_ads_object.campaign_id | 广告计划 ID |
| tracker_sub_campaign_name | te_ads_object.ad_group_name | 广告组名，变现广告的 Unit 名 |
| tracker_sub_campaign_id | te_ads_object.ad_group_id | 广告组 ID，变现广告的 Unit ID |
| tracker_creative_name | te_ads_object.ad_name | 广告名 |
| tracker_creative_id | te_ads_object.ad_id | 广告 ID |
# 四、附录
部分平台会限制用户粒度数据回传到其他第三方平台，其中也包括使用 Internal BI Postbacks 回传到 TE 系统。以下表格展示的是这些平台的限制规则：
| 平台名 | 限制规则 |
|---|---|
| Facebook 用户粒度数据会在归因后的 6 个月清除，因此在归因的 6 个月后，Facebook 的归因用户会在 Singular 系统中被标识为 "Organic"（即自然量）。同时获取 Facebook 展示归因的用户粒度数据在最终用户协议中是不被允许，因此 Facebook 展示归因用户的归因信息都会被标记为 "Unattributed" | |
| Google Ads (Adwords) | Google Ads 用户粒度数据会在归因后的 6 个月清除，因此在归因的 6 个月后，Google Ads 的归因用户会在 Singular 系统中被标识为 "Organic"（即自然量） |
| Snapchat | Snapchat 的数据分享政策禁止任何 Snapchat 数据分享给第三方 |
| TikTok | TikTok 用户粒度数据会在归因后的 6 个月清除，因此在归因的 6 个月后，Tiktok 的归因用户会在 Singular 系统中被标识为 "Organic"（即自然量）。同时获取 Tiktok 展示归因的用户粒度数据在最终用户协议中是不被允许，因此从 2022-05-02 之后的 Tiktok 展示归因用户的归因信息都会被标记为"TikTok Restricted" |
| 请确认您的 Twitter 接入点有资格接收 Twitter 的设备粒度归因数据 Twitter用户粒度数据会在归因后的 6 个月清除，因此在归因的 6 个月后，Tiktok 的归因用户会在 Singular 系统中被标识为 "Organic"（即自然量）。另外，Twitter 最终用户有权将他们的数据从第三方处删除，这些用户的数据不会出现在用户粒度数据中，但仍会在聚合数据中被计算 |