更新记录

1.0.0（2026-07-14）

插件首次发布

平台兼容性

uni-app(4.71)

uni-app x(4.71)

gt-appsflyer-uts

适用于 uni-app、uni-app x 的 AppsFlyer 移动归因插件，支持 Android 和 iOS。

插件提供 SDK 初始化、应用内事件上报、安装归因、App Open Attribution、统一深度链接（UDL）、AppsFlyer UID、GAID/IDFA、客户用户 ID、OneLink 邀请链接、邀请事件、卸载测量和 iOS ATT 授权等能力。

支持平台

仅支持 App-Android 和 App-iOS，不支持 Web、小程序和 HarmonyOS。

使用前准备

1. 配置 AppsFlyer 应用

1. 登录 AppsFlyer 后台并添加应用。
2. Android 应用填写与打包项目一致的包名。
3. iOS 应用填写与打包项目一致的 Bundle ID，并取得 App Store 数字 ID。
4. 在 AppsFlyer 后台取得 Dev Key，初始化插件时通过 devKey 传入。

调试基座、正式包的 Android 包名和 iOS Bundle ID 必须与 AppsFlyer 后台登记的信息一致。iOS 的 App Store ID 只填写数字，不要包含 id 前缀。

2. 制作自定义基座

本插件包含 Android、iOS 原生 SDK，标准基座不包含插件代码。安装插件或升级插件版本后，需要重新制作并安装对应平台的自定义基座；直接云端正式打包时，重新提交正式包即可。

3. Android 注意事项

• 最低支持 Android 5.0（API 21）。
• 插件依赖 Install Referrer 和 Google Advertising ID 组件。
• 使用 getGaid 或广告标识相关归因能力时，应根据应用投放地区、上架商店要求和用户授权情况完成隐私披露。
• collectAndroidId、collectImei 默认关闭，仅在业务确有需要且符合隐私要求时开启。

4. iOS 注意事项

• 最低支持 iOS 12.0，仅包含真机所需的 arm64 架构。
• 插件已包含 NSUserTrackingUsageDescription，上架前请在 utssdk/app-ios/Info.plist 中改成与应用实际用途一致的说明。
• iOS 14 及以上读取有效 IDFA 前，需要通过 requestTrackingAuthorization 请求 ATT 授权。
• 如需等待 ATT 结果后再发送归因数据，可在 initSdk 中设置 waitForAttAuthorizationSeconds，并在超时时间内请求 ATT。
• Windows 上调试 iOS UTS 插件时，需要云端制作包含本插件的 iOS 自定义基座。

5. OneLink 与深度链接

使用 OneLink 邀请链接或 UDL 前，需要先在 AppsFlyer 后台创建 OneLink 模板，并按照 AppsFlyer 要求配置 Android App Links、iOS Universal Links 及关联域名。inviteOneLinkTemplateId 填写 OneLink 模板 ID。

引入插件

import {
  setRequestListener,
  setConversionListener,
  setDeepLinkListener,
  initSdk,
  logEvent,
  setCustomerUserId,
  getAppsFlyerUID,
  getSdkVersion,
  getGaid,
  generateInviteLink,
  logInvite,
  stop,
  updateServerUninstallToken,
  requestTrackingAuthorization
} from '@/uni_modules/gt-appsflyer-uts'

初始化

建议先注册需要的监听器，再调用一次 initSdk。重复初始化会返回 code: 400。

setRequestListener((res) => {
  console.log('AppsFlyer 启动结果：', res)
})

setConversionListener((res) => {
  console.log('AppsFlyer 安装归因结果：', res)
})

setDeepLinkListener((res) => {
  console.log('AppsFlyer 深度链接结果：', res)
})

const config = {
  devKey: '你的 AppsFlyer Dev Key',
  appleAppStoreId: '你的 iOS App Store 数字 ID',
  debugMode: false,
  observeInstallAttribution: true,
  observeDeferredDeepLinks: true,
  waitForAttAuthorizationSeconds: 60
} as UTSJSONObject

initSdk(config, (res) => {
  console.log('AppsFlyer 初始化结果：', res)
})

setRequestListener 和 initSdk 的回调都会收到 SDK 启动结果；不需要两份启动日志时，保留其中一种即可。

页面级注册长期监听时，建议在页面卸载时解除，避免已经销毁的页面继续接收回调：

onUnload(() => {
  setRequestListener(null)
  setConversionListener(null)
  setDeepLinkListener(null)
})

initSdk 配置

API

setRequestListener

监听 SDK 启动结果。code: 200 表示启动成功，code: 440 表示启动失败。传空参数可解除监听。

setRequestListener((res) => {
  console.log(res.code, res.msg)
})

setConversionListener

监听安装归因与 App Open Attribution。payload 是 JSON 字符串。

安装归因通常与首次安装、首次启动及 AppsFlyer 后台归因状态有关，不会在每次调用 initSdk 时都返回新数据。

setDeepLinkListener

监听 AppsFlyer 统一深度链接结果。成功时返回 code: 203，链接信息位于 payload JSON 字符串中。传空参数可解除监听。

setDeepLinkListener((res) => {
  const payloadText = res.payload
  if (payloadText != null) {
    console.log('深度链接数据：', payloadText)
  }
})

logEvent

上报应用内事件。事件参数支持字符串、数字和布尔值。

const eventParams = {
  af_revenue: 9.99,
  af_currency: 'USD',
  af_content_id: 'demo_sku'
} as UTSJSONObject

logEvent('af_purchase', eventParams, (res) => {
  console.log('事件上报结果：', res)
})

无事件参数时，第二个参数传 null。

setCustomerUserId

设置业务侧用户 ID。建议在 initSdk 前设置，以便后续归因数据关联用户。

setCustomerUserId('user_10001', (res) => {
  console.log('用户 ID 设置结果：', res)
})

getAppsFlyerUID

获取 AppsFlyer UID，成功结果的 payload 格式为 {"appsFlyerUID":"..."}。

getAppsFlyerUID((res) => {
  console.log('AppsFlyer UID：', res.payload)
})

getSdkVersion

获取当前 AppsFlyer SDK 版本，成功结果的 payload 格式为 {"version":"..."}。

getSdkVersion((res) => {
  console.log('SDK 版本：', res.payload)
})

getGaid

获取广告标识符。为方便跨平台统一调用，iOS 仍使用方法名 getGaid。

• Android：payload 包含 gaid 和 isLimitAdTrackingEnabled。
• iOS：payload 包含 idfa。用户未授权 ATT 时，可能返回全零 IDFA。

getGaid((res) => {
  console.log('广告标识结果：', res.payload)
})

generateInviteLink

生成 OneLink 用户邀请链接。调用前需在 initSdk 中配置 inviteOneLinkTemplateId。

const inviteOptions = {
  channel: 'app_invite',
  campaign: 'invite_campaign',
  deeplinkPath: 'invite/detail',
  userParams: {
    af_sub1: 'user_10001'
  }
} as UTSJSONObject

generateInviteLink(inviteOptions, (res) => {
  console.log('邀请链接：', res.payload)
})

成功结果的 payload 格式为 {"url":"..."}。

logInvite

记录邀请事件。

const invitePayload = {
  referrerId: 'user_10001'
} as UTSJSONObject

logInvite('app_invite', invitePayload, (res) => {
  console.log('邀请事件结果：', res)
})

stop

暂停或恢复 AppsFlyer SDK。传 true 暂停数据发送，传 false 恢复。

stop(true, (res) => {
  console.log('暂停结果：', res)
})

updateServerUninstallToken

向 AppsFlyer 注册卸载测量 Token。

• Android：传入 FCM Token 字符串。
• iOS：传入 APNs deviceToken 的十六进制或 Base64 字符串。

updateServerUninstallToken('你的 FCM 或 APNs Token', (res) => {
  console.log('卸载 Token 更新结果：', res)
})

卸载测量还需要在 Firebase、APNs 和 AppsFlyer 后台完成相应配置，仅调用该方法不能独立完成卸载测量接入。

requestTrackingAuthorization

请求 iOS ATT 授权。Android 调用时返回成功，msg 为 not applicable on Android。

requestTrackingAuthorization((res) => {
  console.log('ATT 授权结果：', res.payload)
})

iOS 14 及以上的 payload.status 对应系统原始状态：0 未决定、1 受限制、2 拒绝、3 已授权；iOS 14 以下返回 -1。

返回结果

所有异步 API 使用统一回调结构：

{
  code: 200,
  msg: 'ok',
  payload: '{"key":"value"}'
}

状态码说明

201、202、203 都是成功的监听事件，不应当作为错误处理。普通 API 通常使用 code == 200 判断成功；监听器应根据具体事件码分别处理：

setConversionListener((res) => {
  if (res.code == 201) {
    console.log('安装或转化数据：', res.payload)
  } else if (res.code == 202) {
    console.log('App Open Attribution：', res.payload)
  } else if (res.code == 401 || res.code == 402) {
    console.error('归因回调失败：', res.msg)
  }
})

setDeepLinkListener((res) => {
  if (res.code == 203) {
    console.log('深度链接数据：', res.payload)
  } else {
    console.error('深度链接处理失败：', res.msg)
  }
})

隐私与合规

AppsFlyer SDK 可能处理设备标识符、广告标识符、IP 地址、应用信息、安装信息和应用内事件，并将相关数据发送至 AppsFlyer 服务。开发者需要根据实际启用能力完成以下工作：

• 在应用隐私政策中说明 AppsFlyer 的数据处理目的、类型和共享对象。
• 按投放地区和应用商店要求，在采集广告标识符或上报事件前取得必要授权。
• 在 Google Play 数据安全、App Store App Privacy 等上架表单中如实申报。
• 不要在调试日志中长期输出归因数据、广告标识符或用户标识。

AppsFlyer 的具体数据处理规则以 AppsFlyer 隐私政策和开发者后台配置为准。

常见问题

• 运行时提示插件不存在：当前安装的基座未包含本插件，请重新制作并安装自定义基座。
• Android 没有安装归因数据：确认包名、Dev Key、Install Referrer、AppsFlyer 后台应用状态及测试设备是否按 AppsFlyer 测试流程重新安装。
• iOS 没有安装归因数据：确认 Bundle ID、App Store ID、Dev Key 与 AppsFlyer 后台一致，并按测试流程重新安装应用。
• IDFA 为全零：用户尚未授权 ATT、已拒绝授权或系统限制了广告跟踪。
• 没有深度链接回调：确认 OneLink 模板、关联域名、Android App Links、iOS Universal Links 和 AppsFlyer 后台配置完整。
• payload 无法直接读取字段：payload 是 JSON 字符串，需要先判空再解析。

AppsFlyer 官方开发文档：https://dev.appsflyer.com/hc/