跳到主要内容

AppsFlyer FAQ（自查版）

最近更新 2026/10/07

1. Push Api​

1.1 初始化 SDK 顺序（必看）​

警告

数数& AF SDK 需要严格按照以下流程初始化及接口调用

  • 初始化数数客户端 SDK
  • 通过调用自动集成或手动集成接口将 distinct_id 设置到三方事件中（设置代码参考官方文档AppsFlyer Push API 本文不再做赘述）
  • 初始化 AF SDK

1.2 AE 配置 - 数据源下终端地址为空处理​

  • 在 AE 后台项目管理 — 接入配置— 数据上报地址中添加 8991 端口的服务器地址，可以向您公司运维同事确认。之后 AppsFlyer 平台终端地址会自动同步进来。

1.3 回传方案的几种状态详解​

1.3.1 状态一：接入异常​

  • 接入异常的原因

    • 创建或更新 AF 回传方案后 2 小时内无数据回传。
    • 72 小时内有数据接入但存在转化失败，或超过 72 小时没有新的事件回传。

  • 转化失败原因解析

    • 查看数据转化失败的原因，点击方案右上角「详情」图标，在数据详情中查看转化失败的原因

    • 场景：“转化失败，原因：用户 ID 无法关联”

      • 问题原因一：没有按照文档要求将 AE 用户标识赋值给 AF 事件导致
      • 问题原因二：旧版本 APP 没有设置用户标识到 AF 事件或者没有集成数数 SDK
      • 具体排查流程请参考 ：三方数据回传用户转化失败排查最佳实践

1.3.2 状态二：已接入​

  • 若平台接入状态为「已接入」，则说明已经从该平台接收到了数据，并且数据已经入库，此时您可以直接在集成页或每个平台的配置页点击「详情数据」查看收到的最近 1000 条数据：

1.3.3 状态三：等待接入​

  • 配置完成后没有事件回传到 AE 或修改方案后没有新数据回传到 AE

1.4 AF-install 与 AE-ta_app_install 事件数量不一致问题​

  • 通常情况是因为安装事件采集规则有所不同，ta_app_install的采集规则是只要 APP 有新安装或卸载重装行为，都会触发一次。而af sdk install有一定的窗口期，窗口期内卸载重装不会再次上报安装事件。AF 窗口期相关请参考下面文档：再归因窗口期详解

  • 除了天然存在的差异外，其他数据差异的排查步骤（建议按照 1，2，3 顺序排查）如下：

    使用接口激活差异应用内事件差异

    Push API

    1.对比抽样时间是否太短、对比时区是否一致

    2.是否有的 App 版本没有接入 AE SDK 或者 AppsFlyer SDK

    3. AE 服务器接收到 AppsFlyer 的 install 事件是否含有 Custom Data/Customer User Id 字段，并且值正常不为空

    4.AppsFlyer 后台下载原始数据 Custom Data/Customer User Id 字段的键名是否为 ta_account_id， ta_distinct_id

    5.AppsFlyer 后台下载原始数据 Custom Data/Customer User Id 字段是否缺失值

    5.1 不为空的话，就是 Push API 推送设置的时候没选 Custom Data/Customer User Id；

    5.2 为空的话，就是客户端 SDK 没有上报 Custom Data/Customer User Id

    6.AppsFlyer SDK 通过 setAdditionalData() 或者 setCustomerUserId() 上报 ta_account_id 或 ta_distinct_id 失败率是否较高

    7.请检查服务器的安全组入方向授权对象配置，也可以将所有 AppsFlyer IP 地址列入白名单

    1. 是否打开了 AppsFlyer 事件表数据入库的配置
    2. 对比抽样时间是否太短、对比时区是否一致
    3. 是否有的 App 版本没有接入 AE SDK 或者 AppsFlyer SDK
    4. 成本差异：是否接入了 Facebook， Google 等 SRN 渠道，这些渠道的成本数据无法通过 Push API 获取；
    5. 收益差异：检查用于承载收益的事件名是什么，并确定该事件是 AppsFlyer 批量获取还是实时获取

1.5 回传事件都转化成功了，但查不到数据的原因是什么​

  • 请确认项目是否开启了强校验模式。若已开启，建议先关闭该模式，等回传一批数据后再重新开启。
  • 确认是否为强校验模式：点击右上角设置按钮，找到项目管理并点击，然后查看数据处理规则。

1.6 其它​

1.6.1 渠道 media_source 显示 restricted 或者转化后用户属性只有 media_source 问题​

  • 可以参考基于 Google Install Referrer 获取 AppsFlyer 安卓 FB 用户级别数据的方案。

1.6.2 AppsFlyer 渠道 media_source 为空，但是推广活动名称有值​

  • 一般和代理透明度相关，需要把代理透明度开启再观察下，详细可以参考文档。

1.6.3 S2S 的数据如何接入并转化​

  • AppsFlyer S2S 数据在接入时需上报从客户端 SDK 获取的 customer_user_id 或 custom_data 字段用于后续和 AE 用户进行绑定，S2S 字段具体上报细节请参照 AppsFlyer 移动设备的 S2S 事件 API（S2S-mobile）

1.6.4 AppsFlyer Push API Raw data 数据如何下载​

  • 进入AppsFlyer后台，到面板左边引导栏，进入 Export-Raw Data Export，之后选择 organic及非organic下的事件，点击create，之后选择customize，需要勾选 custom_data 字段之后再下载数据

1.6.5 te_ads_object 属性表示什么意思，能否存入其他字段​

  • te_ads_object对象是一个标准化的对象字段，用于将不同三方平台中字段名不同但含义相同的字段统一存储在该对象中，以便后续进行分析。
  • 可以的，可以在用户属性入库规则配置模块配置，来源数据名为转化前字段目标属性名为入库字段名
    • 举例：将 af 回传的原始数据字段 idfa 映射到te_ads_object对象中。

2. Pull/Master/Cohort Api​

2.1 拉取频率的配置建议​

API是否支持拉取当天数据拉取频次应该如何选取
Pull API

是

无实时需求，建议每日中午 12 点（UTC）拉取 AppsFlyer 最近 3-7 天数据；需高实时，则每小时拉取。

Master API

否

无实时需求，建议每日中午 12 点（UTC）拉取 AppsFlyer 过去 3-7 天数据；需高实时，则每小时拉取。
Cohort API否无实时需求，建议每日中午 12 点（UTC）拉取 AppsFlyer 过去 3-7 天数据；需高实时，则每小时拉取。

2.2 相同方案如何配置多个 App ID？​

  • 多个 App ID 之间用英文逗号 , 隔开就好，如下图所示

2.3 重复拉取相同时间范围的数据是否会出现重复数据？​

  • 多次拉取相同时间范围的数据不会导致数据重复。相同时间范围的数据将会被新数据整体覆盖

2.4 拉取事件名如何修改？​

  • Pull Api

    • 如果您配置拉取的是 partner 数据，请修改 event_mapping 对象中 partner 的对应值。
    • 如果您配置拉取的是 geo 数据，请修改 event_mapping 对象中 geo 的对应值。

  • Master Api

    • 修改 event_name 对应的值即可

  • CohortApi

    • 修改 event_name 对应的值即可

2.5 确认数据拉取成功、失败方式​

  • 配置成功后，点击方案右上角单次拉取，拉取结果将通过站内信通知。
  • 拉取成功示例
  • 拉取失败示例

2.6 指定时区拉取 AF 数据配置​

  • 添加 extra_params - timezone 配置，完整示例如下

    提示
    • AF 官网解释
    • 示例 
      • {
          "extra_params": {
            "timezone": "China%2FShanghai"
          },
          "sink_event": {
            "event_mapping": {
              "geo": "appsflyer_geo_data",
              "partner": "appsflyer_partner_data"
            }
          },
          "sink_user": [],
          "source": {
            "report_types": [
              "partner"
            ]
          },
          "transfer": {
            "fields_whitelist": [
             " 。。。。"
            ],
            "double_columns": [
             " 。。。。"
            ]
          }
        }

2.7 是否支持 SKAN 数据回传 ？​

  • 暂不支持：由于 iOS 平台限制，目前无法将 AE 用户标识设置到 SKAN 事件中

2.8 拉取常见异常及处理方案​

  • Create event and props failed!

    • 此错误通常发生在首次拉取数据或新增方案拉取字段时，可能由于服务器过载导致新字段创建失败而引发异常。建议您等待大约 10 分钟后再次尝试拉取数据。如果问题仍然存在，请向对接群中的 ThinkingAI 客户成功经理（CSM）或 ThinkingAI 技术对接人反馈。
    图片缺失：img-7250795c0df5

  • Get thirdparty data failed! The possible error is: AppsFlyer - Page Not Found

    • 可能原因一：AF cohort & master API 是 AF 付费 API，请确认是否已开通相关权限。
    • 可能原因二：可能输入了错误的 AppID，请核对 AE 方案中配置的 AppID 是否与 AF 管理后台提供的一致。
    • 可能原因三：App ID 在 AppsFlyer 侧尚未上线，仍处于测试状态。
    • 如以上原因都不是，请向对接群中的 ThinkingAI 客户成功经理（CSM）或 ThinkingAI 技术对接人反馈。
    图片缺失：img-504127009267

2.9 其它​

2.9.1 拉取的数据和 AppsFlyer 面板上的数据对不上问题​

  • 确认在 AppsFlyer 核对的指标是否和 AE 后台核对的数据指标一致；

    • 分析是否是维度不一样或参数配置导致数据差异
    • 选择的应用/成本渠道不一致

  • 确认 AppsFlyer 平台面板数据的时区和方案拉取时区是否一致（方案默认 UTC 时区拉取数据）

  • AppsFlyer api 数据有延迟和更新变化，如果个别日期的数据不准确请尝试点击方案右上角单次拉取重新拉取试下；

  • 如果排查以上信息仍未解决可以联系 ThinkingAI 技术支持协助排查。

2.9.2 AppsFlyer 控制面板群组分析报表的收益数据和 Master API 拉取的数据对不上问题​

  • 如下图使用 AppsFlyer 的群组看板查看收益数据为激活后的累计数， 需要调用 Cohort api 拉取数据核对。
    图片缺失：img-e47832d7ddef

2.9.3 通过 Cohort API 拉取回来的数据，FB 渠道无 cost 值问题​

  • 因为 cost 不是汇总数据，不同分组项可能会导致数据差异， 如当 Geo 和 Channel 同时作为分组项的时候，FB 的 cost 值为 0。 AF 官方文档说明：成本指标不能与某些分组维度相结合。如 Facebook 的数据可以按 Geo（国家/地区）或 Channel（流量入口）分组，但不能同时结合这两个维度进行分组。具体的可用分组维度组合取决于广告平台。具体请联系 ThinkingAI 技术支持协助处理。

2.9.4 通过 Cohort API 拉取回来的数据，applovin渠道无 cost 值问题​

  • 将group_by设置为 "date","c","pid" 检查是否有cost数据。

2.9.5 AppsFlyer Master API 近 7 天 cost 数据与 AF 后台数据概览看板对不上​

补充问题​

部分数据显示without_id​

  • 检查without_id的App version是否一致
  • 确认最新版应用是否也有without_id情况
  • 检查客户端ID绑定逻辑，确保先初始化数数SDK→传ID给AF→初始化AF SDK

从AF转到Adjust需要注意什么​

  • 需要将访客ID赋值给Adjust（需重新发版）
  • 成本数据建议接入Adjust Report API
  • 如有 Facebook 投放，需参考 Adjust 实时回传附录 配置 Facebook 详细广告信息

AE FB渠道用户数据比AF后台还多​

  • 原因：install事件和af_app_install事件都是AF平台回传到 AE 的数据，AF平台统计这两个事件是同一类行为的不同数据来源
  • 解决：注意区分事件定义

AF revenue raw data 拉取失败​

  • 原因：group by配置问题
  • 解决：检查group by配置，确保包含 gp_install_begin、campaign_type、att、keyword_match_type、conversion_type 等必要字段

AF pull raw data 不支持timezone字段​

  • Pull API raw data接口不支持时区设置

AF拉取再营销消耗​

  • 需要用Cohort API拉取再营销消耗或包含再营销消耗

AF meta数据country拉取为0​

  • 原因：配置缺少event_mapping
  • 解决：替换标准配置，保存方案后重新拉取。先拉取今天一天的数据，成功后再拉取历史数据

AF master FB消耗对不上​

  • 原因：文档提示geo和channel不能同时传入
  • 解决：都删了才能和AF后台对上

配置补充​

如何添加入库字段白名单（fields_whitelist）​

在transfer中添加fields_whitelist，格式为["field_1", "field_2"]，用于控制哪些字段需要入库：

"transfer": {
  "double_columns": ["impressions", "installs", "loyal_users"],
  "fields_whitelist": ["agency_pmd_af_prt", "app_id", "arpu"]
}

如何设置Master API时区​

Master API默认UTC时区，可通过extra_params设置timezone为preferred（应用时区）：

"extra_params": {"timezone": "preferred"}

如何设置Cohort API时区​

preferred_timezone默认为true（应用时区）。如需设置为UTC时区，需将preferred_timezone置为false，使用custom_properties（base64 编码）：

"extra_params": {
    "custom_properties": "eyJwcmVmZXJyZWRfdGltZXpvbmUiOmZhbHNlfQ"
}

如何通过Cohort获取总消耗​

获取总消耗（包含再营销cost数据），设置{"cohort_type":"unified"}：

"extra_params": {
    "custom_properties": "eyJjb2hvcnRfdHlwZSI6InVuaWZpZWQifQ=="
}

如何设置Cohort聚合类型​

aggregation_type=on_day时返回独立session数据（如sessions_unique_users_day_*），此时partial_data必须置为false：

{"extra_params": {"aggregation_type": "on_day", "partial_data": "false"}}

异常补充​

AF Pull API 报错 403 Limit reached for partners-report​

  • AF对API拉取有频次限制，注意控制拉取频率。

AF pull raw data revenue 请求失败​

  • 如需移除campaign_type、att、keyword_match_type、conversion_type等无效字段，检查并调整group by配置。
这篇文档对你有帮助吗？
本页内容