Singular数据集成

适用于 SA 3.0.5 及以上版本。

该功能由 License 控制。若有使用需求，请联系您的客户经理。

集成功能介绍

本文将介绍如何将 Singular 的用户级归因数据接入神策分析系统中。Singular 接入使用 Internal BI Postbacks 实时回传方式，神策分析接收到 Singular 推送的数据后，可按配置写入事件表，并在满足条件时更新海外归因表。

Singular 接口	数据粒度	API 类型	数据更新频率
Internal BI Postbacks	用户级别	Singular 服务端实时回传	实时

注意：

1. 使用前请确认您的 Singular 账号具备配置 Internal BI Postback 的权限。

2. Singular 回传字段和归因结果以 Singular 实际推送内容为准。若 Singular 未返回某个字段，神策分析不会自行补齐该字段。

3. 写入事件表的数据会计入数据量消耗。建议只配置确实需要分析的应用内事件。

Singular 原始数据接入

您可以通过 Singular Internal BI Postbacks 将 Singular 的 Install 激活事件和应用内事件实时回传至神策分析系统。接入后，神策分析支持以下能力：

• 将 Singular 回传的 Install 激活事件写入神策事件表，用于查看和分析 Singular 归因激活数据。

• 将配置接入的 Singular 应用内事件写入神策事件表，用于分析不同归因来源下的后续转化表现。

• 将带神策用户唯一 ID 的 Install 明细数据记录至海外归因表，用于查询神策上报用户行为对应的海外渠道来源。

• 支持查看默认消息字段映射，并按需添加 Singular 回传字段，作为事件属性和三方归因属性进行分析。

接入流程

若您首次使用 Singular 用户归因数据接入功能，需要依次完成以下配置：

1. 集成并配置 Singular SDK 和神策 SDK

   在 App 中同时集成 Singular SDK 和神策 SDK，并在客户端中通过神策 SDK 获取神策用户标识，将该标识传入 Singular SDK。这样 Singular 后续回传 Install 或应用内事件时，才能携带神策用户识别信息。

2. 在 Singular 平台配置 Internal BI Postback

   将神策分析平台中 Singular 接入配置页面生成的数据接收地址复制到 Singular 后台，并配置需要推送的事件类型。

3. 在神策分析平台中开启数据接收和事件写入，按需添加其他自定义消息字段

   在神策分析平台中打开 Singular 数据接收开关，并按需配置事件写入规则和消息字段映射。配置完成后，神策分析会按照配置规则接收、解析和写入 Singular 回传数据。

完成以上配置后，您可以在神策分析模型中查询 Singular 接入事件，也可以查询神策采集事件关联的海外渠道归因结果。

客户端 SDK 设置

若要将 Singular 回传数据与神策分析系统中的用户行为做用户级关联，需要在 Singular SDK 中传入神策用户标识。

神策分析会使用 Singular 回传中的神策用户唯一 ID （$distinct_id）和用户登录标识（$is_login）识别用户。若回传数据中缺少神策用户唯一 ID，系统将无法使用该 Install 明细数据更新海外归因表。

请在客户端接入阶段确认以下事项：

• App 已正确集成 Singular SDK 和神策 SDK。

• 客户端可获取神策用户唯一 ID 和登录标识。

• 神策用户标识已按约定传入 Singular SDK。

• Singular 回传数据中可携带上述神策用户识别信息。

详细配置流程请参考  三方数据接入指南（Android） 、三方数据接入指南（iOS）

设置 Singular Internal BI Postback

您需要使用具备配置权限的账号登录 Singular 后台，并完成 Internal BI Postback 配置。

请按照以下方法设置 Singular 回传：

1. 登录 Singular 账号。

2. 进入 归因设置 > 配置渠道。

3. 点击 添加渠道合作伙伴 ，即 Internal BI Postback。

4. 搜索找到 Sensors Data。

5. 将神策分析平台 Singular 接入配置页面中的数据接收地址复制并填写至 Postback 回传地址。

6. 按需选择需要推送的事件类型。

7. 保存并启用配置。

注意：

1. 数据接收地址由神策分析平台按项目生成。不同神策项目的数据接收地址不同，请勿混用。

2. 如果您在神策分析中新增自定义接收字段，需要同时确认 Singular 后台已支持并正确配置对应回传参数，否则神策分析无法接收到该字段。

在神策分析中配置 Singular 数据接收

在进行神策分析平台配置前，请确认上文中的客户端 SDK 设置和 Singular 后台配置已完成，否则以下设置将无法生效。

功能入口：

渠道追踪 > 三方数据集成 > 归因生态 > Singular

点击 接入配置 进入配置页面

打开数据接收开关

数据接收配置用于控制是否接收 Singular 推送的数据。

• 数据接收开关：默认关闭。开启后，神策分析可接收 Singular 实时回传数据；关闭后，不再接收 Singular 实时回传数据，也不再更新归因记录
• 数据接收地址：系统生成的回传地址。请将该地址填入 Singular 的 Postback 回传地址中
• 用户识别方案：神策分析使用 Singular 回传中的神策用户唯一 ID 和登录标识识别用户

数据接收开关实时生效，变更状态时请确认配置正确，避免影响实时回传数据结果。

只有当激活（mmp_singular_install）事件接入，数据正常写入归因表后。Singular 对接方案的接入状态才会变为 已接入 。

打开事件写入开关

事件写入配置用于控制是否将 Singular 回传的其他应用内事件写入神策事件表。

写入规则：

• Install 激活事件默认写入事件表，事件名为 mmp_singular_install，无需在目标写入事件中额外配置。

• 其他应用内事件需要先在目标写入事件中配置。

• 其他应用内事件写入神策后，事件名会自动增加 mmp_singular_ 前缀。例如，若配置事件名为 purchase，写入神策后的事件名为 mmp_singular_purchase。

注意：

1. 写入 Singular 回传事件会消耗神策分析套餐中的事件量。

2. 请按照 Singular 实际回传的事件名称配置目标写入事件。事件名称填写错误时，对应事件将无法写入事件表。

3. 变更事件写入配置会实时生效，请谨慎操作。

配置消息字段

消息字段配置用于查看默认接收字段，也可按业务需要配置自定义接收字段。

名词释义如下：

• Singular 字段：Singular 回传数据中的字段名称。

• 神策自定义属性：在事件表中用于接收 Singular 字段的事件属性，通常以 mmp_singular_ 开头。

• 神策三方归因属性：用于统一记录三方归因结果的属性，通常以 mmp_ 开头；实际为虚拟属性；可用于查询神策上报事件关联的海外渠道来源。

• 神策三方首次渠道属性：当用户首次归到媒体渠道时，使用该预置用户属性记录 MMP 的渠道归因结果。使用 profile setonce() 做首次更新

默认接收字段

神策分析默认支持将以下 Singular 消息字段按照预置规则写入事件表，并同步记录至三方归因属性中。默认接收字段仅支持查看，不支持修改。

Singular 字段	神策自定义属性	神策三方归因属性	神策三方首次渠道属性	备注
app_name	mmp_singular_app_name	mmp_app_name
long_name	mmp_singular_long_name	mmp_bundle_id
public_id	mmp_singular_public_id	mmp_public_id
network_name	mmp_singular_network_name	mmp_media_source	mmp_first_media_source
idfa	mmp_singular_idfa	mmp_idfa
aifa	mmp_singular_aifa	mmp_aifa
platform	mmp_singular_platform	mmp_platform
attribution_country	mmp_singular_attribution_country	mmp_attribution_country
attribution_city	mmp_singular_attribution_city	mmp_attribution_city
attribution_state	mmp_singular_attribution_state	mmp_attribution_state
event_name	mmp_singular_event_name	mmp_event_name
created_at_milli	mmp_singular_created_at_milli	mmp_start_time
campaign_name	mmp_singular_campaign_name	mmp_campaign_name	mmp_first_campaign
campaign_id	mmp_singular_campaign_id	mmp_campaign_id	mmp_first_campaign_id
subcampaign_name	mmp_singular_subcampaign_name	mmp_subcampaign_name	mmp_first_adgroup
subcampaign_id	mmp_singular_subcampaign_id	mmp_subcampaign_id	mmp_first_adgroup_id
creative_name	mmp_singular_creative_name	mmp_ad_name	mmp_first_ad
creative_id	mmp_singular_creative_id	mmp_ad_id	mmp_first_ad_id

自定义接收字段

若默认接收字段不能满足您的分析诉求，您可以按需添加自定义接收字段。请严格按照Singular支持的宏参数 列表来添加自定义接收字段，并配置相应的接收该字段的神策属性。

神策将根据您填写的自定义属性名称，自动增加“mmp_singular_“前缀以便区分该属性为 Singular 事件专用，同时自动以”mmp_“前缀创建神策三方归因属性名称，用于统一接收三方渠道归因结果。

配置自定义接收字段后，数据接收地址会自动拼接对应参数。请同时在Singular后台填写已经更新的Postback地址，否则神策分析无法接收到该字段。

举例，若您希望接收的回传事件中包含APP_NAME信息，则可在自定义接收字段中填写APP_NAME，在「神策自定义属性名称」中填写 app_name，点击保存后，即可完成新增的自定义接收字段配置。

含义为，当神策分析系统接收到 Singular 回传的 APP_NAME 消息字段时，在写入事件的同时将自动新建 mmp_singular_app_name 自定义属性并写入；若接收的事件为激活（mmp_singular_install），也会同时自动新建 mmp_app_name 虚拟属性并写入，后续若相同用户通过神策 SDK 上报行为事件时，可关联查询 mmp_app_name 取值。

注意：

1. 自定义字段需要 Singular 实际回传后才会写入神策分析。

2. 编辑自定义消息字段并保存后，映射规则会实时生效。

3. 请避免频繁修改已用于分析的字段映射，以免影响历史数据和后续查询口径。

数据入库规则

用户识别规则

根据客户端 SDK 中设置的神策用户标识字段，神策默认将按回传的 mmp_singular_install 数据中的以下字段来寻找用户标识：

检查  global_properties 字段是否包含 神策用户唯一ID（$distinct_id）、神策用户登录标识（$is_login），即神策透传给 Singular 的用户标识字段。

如果能获取到有效的用户标识，则根据神策用户标识记录该用户。

若无法获取有效神策用户标识，则该条数据将不记录入库。

注意

若您在神策分析系统采用了特殊的用户标识字段（使用上述 $distinct_id 与 $is_login 无法准确识别您的用户），请联系您的商务经理。我们将在交付阶段做出调整，以便适配您的业务情况。

事件入库规则

只要打开数据接收开关，神策分析默认会将接收到的 Install 激活事件写入事件表。若您在事件写入配置中配置了其他应用内事件，系统也会按配置写入。

事件数据的入库规则如下：

• 根据用户识别规则，写入的事件数据会关联到对应神策用户。

• 使用 Singular 回传数据中的 created_at_milli 作为事件时间。

• Install 激活事件默认写入为 mmp_singular_install。

• 其他应用内事件写入为 mmp_singular_{事件名}。

• Singular 回传字段会按 mmp_singular_ 属性写入事件表。

• 三方归因字段会按 mmp_ 属性记录，用于统一分析。

用户属性入库规则

当系统接收到 Singular 回传的Install事件并识别到对应用户后，会按规则更新用户相关属性。若该用户此前尚未记录首次三方渠道属性，系统会根据 Singular 回传的归因字段执行首次更新。

首次三方渠道属性用于记录用户首次归因到媒体渠道时的来源信息，后续可用于分析不同首次渠道来源用户的转化表现。

神策首次三方渠道属性 （预置用户属性）	Singular 消息字段名称	备注
mmp_first_media_source	network_name	媒体渠道
mmp_first_campaign	campaign_name	广告系列名称
mmp_first_campaign_id	campaign_id	广告系列 ID
mmp_first_adgroup	subcampaign_name	广告组
mmp_first_adgroup_id	subcampaign_id	广告组 ID
mmp_first_ad	creative_name	广告名称
mmp_first_ad_id	creative_id	广告 ID

三方归因表更新规则

神策分析支持保存三方归因平台的归因结果，并通过已打通的神策用户标识，将神策上报的用户行为与三方归因结果进行关联。

Singular 三方归因表更新规则如下：

• 当且仅当接收到带神策用户唯一 ID 的 Install 明细数据时，系统会更新海外归因表。

• 若该用户此前没有归因记录，系统会新增一条归因记录。

• 若该用户此前已有归因记录，系统会按 Install 事件时间插入或更新归因记录，并维护对应归因记录的起止时间。

• 如果 Install 明细数据中缺少神策用户唯一 ID，系统不会使用该数据更新海外归因表。

数据查询方法

完成上述配置后，您可以在事件分析中查询接入的 Singular 事件，也可以查询神策上报事件关联的三方归因渠道结果。

查询接入的 Singular 事件

以默认接入的 Install 事件为例：

1. 进入事件分析。

2. 选择事件 mmp_singular_install。

3. 在分组项中选择 Singular 三方归因属性，例如 mmp_media_source、mmp_campaign_name。

4. 查看不同 媒体来源或 Campaign 下的 Singular 激活数据。

若您配置了其他应用内事件，也可以选择 mmp_singular_{事件名} 进行查询。请确保查询的事件名称与事件写入配置一致。

查询接入的 Singular 用户

您可以使用三方首次渠道属性分析 Singular 接入用户的首次渠道来源。

以默认接入的 Install 事件为例：

1. 进入事件分析。

2. 选择事件 mmp_singular_install。

3. 在分组项中选择三方首次渠道属性。

4. 查看不同首次渠道来源下的用户规模和转化表现。

查询神策上报事件关联的三方归因渠道结果

如果您希望分析神策 SDK 采集的用户行为与 Singular 归因来源之间的关系，可以在事件分析中查询神策上报事件，并使用三方归因属性分组。

例如，分析某个 App 内转化事件时：

1. 进入事件分析。

2. 选择神策 SDK 上报的目标事件。

3. 在分组项中选择 mmp_media_source、mmp_campaign_name、mmp_campaign_id、mmp_subcampaign_name、mmp_ad_name 等三方归因属性。

4. 查看不同媒体来源、Campaign、Subcampaign 或 Creative 下的转化表现。

常用 Singular 分析字段包括：

mmp_media_source、mmp_campaign_name、mmp_campaign_id、mmp_subcampaign_name、mmp_subcampaign_id、mmp_ad_name、mmp_ad_id、mmp_platform、mmp_attribution_country、mmp_attribution_city、mmp_start_time。

权限

权限点	说明
查看 Singular	可查看 Singular 接入方案
配置 Singular	可配置 Singular 数据接入

特殊说明和限制

• 数据接收开关关闭后，神策分析不再接收 Singular 实时回传数据，也不再更新归因记录。

• 事件写入开关关闭后，除 Install 激活事件外，其他 Singular 应用内事件不再写入事件表。

• 自定义接收字段需要 Singular 后台同步支持对应回传参数，否则神策分析无法接收到该字段。

• Singular 回传字段和归因结果以 Singular 实际推送内容为准。

• 写入事件表的数据会计入数据量消耗。建议只配置确实需要分析的应用内事件。

本文档内容为神策产品使用说明，不包含适销类条款；具体企业采购产品和技术服务内容，以商业采购合同为准。