1. 集成功能介绍

本文将详细介绍如何将 AppsFlyer 的数据接入至神策分析系统中，包括两种方法，详情如下：

AppsFlyer 接口数据粒度API 类型数据更新频率请求次数限制
Push API原始数据AppsFlyer接口推送实时无限制


注意

1、在使用前请咨询您在 AppsFlyer 的客户经理了解接口的使用权限。

2、部分媒体平台会限制原始数据部分字段回传，包括归因信息、收益数据与成本数据。详情可参见 AppsFlyer 字段文档

2. Push API 原始数据接入

您可以通过 AppsFlyer 的 Push API 接口将其用户行为原始数据回传给神策分析系统。神策将支持以下功能，以便您更好的分析海外推广渠道来源。

1、将 Push API 回传的原始数据按事件、用户存入神策的 Event-User 表，供您查看、分析接收的原始事件与用户；（请注意：将第三方回传原始数据按事件写入数据库后，该部分数据会被纳入集群的消耗事件量）

2、将 Push API 回传的原始数据中的每一次拉新归因结果记录至神策海外归因记录表，供您查看、分析神策上报的用户行为对应的海外渠道来源；

3、除默认的归因信息外，支持您在事件属性、海外归因记录表中按需添加其他 Push API 允许回传的消息字段，供您灵活分析其他海外渠道属性；

2.1. 接入流程

若您首次使用 Push API 原始数据接入功能，在对接阶段您需要依次完成以下配置：

1、集成并配置 AppsFlyer 、神策 SDK

集成 AppsFlyer 客户端 SDK、神策客户端 SDK，并在客户端中通过神策 SDK 获取神策用户标识，并将该标识通过指定接口传入 AppsFlyer 客户端SDK中，以便 AppsFlyer 上报用户行为事件时均携带神策用户标识。

2、在 AppsFlyer 平台配置 Push API 接口

将神策分析平台「三方数据集成」-「AppsFlyer Push API 数据接入」中的数据接收地址复制填写至 AppsFlyer Push API 终端地址中，并在相同位置配置目标回传事件与消息字段。

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

当神策分析系统接收到实时回传数据时，将自动按照您配置的写入规则集成数据。此时，您可在神策分析模型中查询神策、AppsFlyer 用户行为事件与其对应的渠道来源。

2.1.1. 客户端 SDK 设置

若要将 Push API 回传的用户行为与神策分析系统上报的用户行为做用户级打通，需要在 AppsFlyer 客户端 SDK 中上报神策用户标识，以便与神策上报用户进行关联。

该功能使用的神策用户标识为 匿名ID（distinct_id）与 是否登录（is_login），需要按指定流程初始化神策与 AppsFlyer SDK后，调用接口开启该标识的上报。

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

2.1.2. 设置 AppsFlyer Push API 接口

您需要使用管理员账号登录 AppsFlyer 后台，在「对接」-「API 数据接口」中配置 Push API 原始数据回传。

请按照以下方法设置Push API 原始数据回传：

1、HTTP 请求方法（HTTP method）

  • 神策分析系统同时支持 POST 和 GET 两种方式回传，我们建议选择 POST 方式。

2、终端地址（Endpoint URL）

  • 请将神策分析系统「AppsFlyer Push API 接入配置」中的数据接收地址复制填写至此处。请注意，每个神策分析项目均有不同的数据接收地址。

3、事件信息类型（Event Messages）

  • 请至少选中激活（Install）和安装应用内事件（Install in-app events）。若您希望回传其他事件数据，可按需勾选。

4、回传消息字段（Message Fields）

  • 需至少包含以下消息字段：
    • 神策用户标识相关字段：custom_data、customer_user_id、appsflyer_id、idfa、advertising_id
    • 事件上报相关字段：event_time、event_time_selected_timezone、app_id
    • 渠道归因相关字段：media_source、network_account_id、campaign、af_c_id、af_adset、af_adset_id、af_ad、af_ad_id、af_keywords、keyword_id、conversion_type
    • 按需添加其他需要作为事件属性或三方归因属性的字段
  • 若无特殊诉求，建议您勾选全部消息字段。

5、回传应用内事件（In-app events）

  • 按需选择回传的应用内事件，例如客户端上报的 purchase 事件


注意

若需要回传 Facebook 的原始数据，需要您在 AppsFlyer 后台 Facebook 渠道设置中统一 Facebook数据使用协议（Terms of Service），否则无法获取 Facebook 的用户级别原始数据。

完成以上步骤后，您便成功在 AppsFlyer Push API 回传端点中设置好了神策分析系统端点。接下来您需要在神策分析平台中继续完成 AppsFlyer Push API 相关数据接收配置。

2.1.3. 在神策分析中配置 AppsFlyer Push API 数据接收

在进行平台功能设置之前，请务必确认 2.1.1、2.1.2 已完成，否则以下设置将无法生效。

2.1.3.1. 打开数据接收开关

在「三方数据集成」中，找到「AppsFlyer Push API」功能，点击「接入配置」按钮进入配置页面

点击「数据接收配置」编辑按钮，并勾选「开启数据接收」，保存。当「生效状态」为「已开启」时，即已打开数据接收开关。

需注意：数据接收开关实时生效，变更状态均会二次确认。请勿随意变更状态，以免影响实时回传数据结果。

2.1.3.2. 打开事件写入开关

点击「事件写入配置」编辑按钮，并勾选「开启事件写入」，此时，您可根据 2.1.2 中在 AppsFlyer Push API 中设置的回传事件，配置您希望接收的用户行为事件。神策分析系统将按照 “mmp_af_目标事件名称”的格式将原始数据写入event表，并记录对应的user表信息。

举例：若您希望在神策分析系统中记录 AppsFlyer 回传的 payOrder 事件，您首先需要确保 AppsFlyer 已上报该行为事件，再确保 Push API 回传应用内事件中添加了该事件，最后再在神策「事件写入配置」中开启事件写入功能，并添加“mmp_af_payOrder”事件。如此，当 AppsFlyer 回传 payOrder 事件时，神策分析系统将自动写入事件表。

注意

1、写入 AppsFlyer 回传事件将消耗您神策分析套餐中的事件量；特殊的，当开启数据接收功能后，无论您是否开启事件写入，激活事件（Install）均会写入事件表消耗套餐事件量，以实现神策与 AppsFlyer 归因打通功能。

2、请务必按照 AppsFlyer 中配置的回传事件字段，填写准确的事件名称（可与您的 AppsFlyer 客户经理 或 SDK 开发人员确认回传事件名称）。该事件名称大小写敏感，填写错误将无法写入事件表。

3、输入事件“visit”并回车后，会自动命名为“mmp_af_visit”，无需重复输入“mmp_af_”。

4、变更事件写入配置将实时生效，均会二次确认。请勿随意变更状态，以免影响实时写入数据。


2.1.3.3. 配置消息字段

默认接收字段

神策默认支持将以下 AppsFlyer 消息字段按照自定义属性写入event表中，并同步记录至神策三方归因属性表中。默认接收字段仅供查看，不支持删改。

名词释义如下：

  • AppsFlyer消息字段名称：AppsFlyer提供的参数字段名称，大小写敏感，请确保与AppsFlyer原始数据字典字段一致
  • 神策自定义属性名称：在event表中，用于接收AppsFlyer事件对应的自定义属性名称；仅适用于AppsFlyer事件查看
  • 神策三方归因属性名称：在三方归因表中，用于统一接收AppsFlyer、Adjust等多家MMP的激活事件的渠道属性字段；实际为虚拟属性；适用于神策上报事件查看MMP渠道归因结果
  • 神策三方首次渠道属性：当用户首次归到媒体渠道时，使用该预置用户属性记录MMP的渠道归因结果。使用profile setonce()做首次更新
AppsFlyer消息字段分组AppsFlyer消息字段名称对应神策自定义属性名称

对应神策三方归因属性名称

对应神策三方首次渠道属性

备注
归因信息media_sourcemmp_af_media_sourcemmp_media_source$mmp_first_media_source媒体渠道
network_account_idmmp_af_network_account_idmmp_network_account_id$mmp_first_network_account_id渠道广告主账户ID
campaignmmp_af_campaignmmp_campaign$mmp_first_campaign广告系列名称
af_c_idmmp_af_campaign_idmmp_campaign_id

$mmp_first_campaign_id

广告系列ID
af_adsetmmp_af_adgroupmmp_adgroup$mmp_first_adgroup广告组
af_adset_idmmp_af_adgroup_idmmp_adgroup_id$mmp_first_adgroup_id广告组ID
af_admmp_af_admmp_ad$mmp_first_ad广告名称
af_ad_idmmp_af_ad_idmmp_ad_id$mmp_first_ad_id广告ID
af_keywordsmmp_af_keywordmmp_keyword/关键词
keyword_idmmp_af_keyword_idmmp_keyword_id/关键词ID
conversion_typemmp_af_conversion_typemmp_conversion_type/转化类型：暂仅支持激活
用户与设备信息custom_data

mmp_af_custom_data_sensors_distinct_id

mmp_af_custom_data_sensors_is_login

//添加了神策用户标识的AppsFlyer消息字段，可从中取出distinct_id与is_login两个字段
customer_user_idmmp_af_customer_user_idmmp_customer_user_id/客户自行设置的用户ID
appsflyer_idmmp_af_appsflyer_idmmp_appsflyer_id/AppsFlyer生成的用户ID
advertising_idmmp_af_advertising_idmmp_advertising_id/安卓设备上可重置的广告ID，通常为GAID
idfammp_af_idfammp_idfa/iOS设备上的可重置的广告ID
应用信息app_idmmp_af_app_idmmp_app_id/AppsFlyer的应用唯一标识








自定义接收字段

若默认接收字段不能满足您的诉求，神策支持您按需添加自定义接收字段。请严格按照 AppsFlyer 原始数据字典 中的参数名称，填写 AppsFlyer 消息字段名称，并填写用于接收的神策自定义属性名称。

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


举例，若您希望将 AppsFlyer 的 app_version 字段，您可在「AppsFlyer消息字段名称」中填写 app_version，在「神策自定义属性名称」中填写 app_version，点击保存后，即可完成新增的自定义接收字段配置。

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

注意

1、无论是默认接收字段或自定义接收字段，使用前，请务必确认在 AppsFlyer Push API 回传消息字段中已勾选如下字段，否则 AppsFlyer 不会回传消息字段，神策也无法接收。

2、与数据接收配置、事件写入配置相同，编辑自定义消息字段并保存后，映射规则将实时生效。请勿随意变更，以免影响数据写入。

3、神策分析接收的自定义属性有长度限制，默认为使用 UTF-8 编码后最大长度 1024 字节。详细说明参考 数据格式

2.2. 数据入库规则

2.2.1. 用户识别规则

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

  1. 检查 custom_data 字段是否包含 sensors_distinct_id / sensors_is_login，即神策透传给 AppsFlyer 的用户标识字段
  2. 检查回传字段中是否包含 af_id，即 AppsFlyer 的用户标识字段

若步骤1中如果能获取到有效的用户标识，则停止步骤2的检查，并根据神策用户标识记录该用户。

若步骤1中无法获取有效神策用户标识，则将步骤2中的 af_id 作为神策匿名id记录该用户。注意，此时该用户无法与神策上报用户关联打通。

若步骤1、2字段均无法获取有效用户标识，将随机生成匿名id记录该用户。注意，此时该用户无法与其他用户关联打通。

注意

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

2.2.2. 事件入库规则

只要打开了数据接收开关，无论是否开启事件写入，神策分析系统默认会将接收到的激活事件（Install）写入事件表。若您在事件写入配置中配置了其他事件写入，神策分析系统也会一同写入。

以下是事件数据的入库规则：

  • 根据神策用户识别规则，写入的事件数据归在对应的神策用户上
  • 使用回传数据中的 event_time 字段，作为事件上报的时间（time）
  • 写入的事件名将在您配置的名称前添加”mmp_af_“前缀，以便与您上报的其他事件区分。特殊的， Install 事件将默认按照 mmp_af_Install 事件写入，无需配置。
  • 写入的事件均会携带自定义属性 mmp_name= AppsFlyer
  • 写入的事件属性名将在您配置的自定义属性名称前添加”mmp_af_“前缀，以便与您上报的其他事件属性区分。以默认接收字段为例（自定义接收字段同理），AppsFlyer 消息字段中的 media_source ，将按照映射写入 mmp_af_media_source 中。

2.2.3. 用户属性入库规则

当接收到任一回传事件，并更新用户表后，若此时该用户无「三方渠道用户属性」，则将执行 profile_set_once() 更新以下首次三方渠道用户属性。

神策首次三方渠道属性

（预置用户属性）

AppsFlyer消息字段名称备注
$mmp_first_media_sourcemedia_source媒体渠道
$mmp_first_account_idnetwork_account_id渠道侧的广告主账户ID
$mmp_first_campaigncampaign广告系列名称
$mmp_first_campaign_idaf_c_id广告系列ID
$mmp_first_adgroupaf_adset广告组
$mmp_first_adgroup_idaf_adset_id广告组ID
$mmp_first_adaf_ad广告名称
$mmp_first_ad_idaf_ad_id广告ID

2.2.4. 三方归因表更新规则

神策分析系统支持接收并保存各家三方归因平台的每一次归因结果，并通过已打通的神策用户标识，将神策上报的用户行为与三方归因结果进行关联。三方归因表更新规则如下：

  • 当且仅当接收到 AppsFlyer 的激活事件（Install），且该激活事件携带了有效的神策用户标识时，更新三方归因表（再营销相关归因结果暂不支持更新）
  • 更新时将以神策用户标识为主key，新增一行归因记录，记录当次归因结果的起止时间、渠道信息
    • 起止时间：新增归因记录时，将始终保证同一个用户的全部归因记录连续、不重复
    • 渠道信息：即写入的三方归因属性（虚拟属性），格式上为在您配置的自定义属性名称前增加”mmp_“前缀

2.3. 数据查询方法

在完成上述配置对接后，可在事件分析中查询接入的 AppsFlyer 事件与用户、查询神策上报事件关联的三方归因渠道结果，方法如下。

2.3.1. 查询接入的 AppsFlyer 事件

以默认接入的 Install 事件为例，在事件分析中筛选事件“mmp_af_install”，在分组选择中勾选自定义属性“mmp_af_app_id”，查询结果示例见下。

您可根据实际诉求，筛选其他配置接入的事件以及自定义属性（务必与事件写入配置、消息字段配置中的名称格式一致，否则将查询不到结果。AppsFlyer的自定义属性均以 mmp_af_开头）

2.3.2. 查询接入的 AppsFlyer 用户

以默认接入的 Install 事件为例，在事件分析中筛选事件“mmp_af_install”，在分组选择中勾选三方用户渠道属性“mmp_first_media_source”，查询结果示例见下。

您可根据实际诉求，筛选其他配置接入的事件以及三方用户渠道属性（默认仅首次更新时写入5个三方用户渠道属性，均以 mmp_first_开头）


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

以 App 内用户行为 payOrder 为例，在事件分析中筛选事件“payOrder”，在分组选择中勾选三方渠道属性“mmp_media_source”，查询结果示例见下。

您可根据实际诉求，筛选其他采集事件以及三方渠道属性（务必与消息字段配置中的名称格式一致，否则将查询不到结果。三方渠道属性均以 mmp_开头）