更新记录

1.0.0（2026-02-02）

init

平台兼容性

uni-app(4.87)

uni-app x(4.87)

hans-appsflyer

uni-app / uni-app x（App 平台）AppsFlyer 归因与事件追踪插件

功能特性

• ✅ 初始化 AppsFlyer SDK
• ✅ 初始化状态监听（onInitStatus）
• ✅ 追踪自定义事件
• ✅ 设置用户 ID
• ✅ 获取 AppsFlyer 设备唯一标识
• ✅ 归因/转化回调监听（Android/iOS）
• ✅ DeepLink 回调监听（Android/iOS）
• ✅ 隐私合规控制（setTrackingEnabled）
• ✅ OneLink 邀请链接（Android/iOS）
• ✅ 获取 GAID / Advertising ID（Android/iOS）

支持平台

使用方法

初始化 SDK

uni-app / uni-app x 用法一致（在 .vue 里用 JS/TS 调用；在 .uvue 里也可用 UTS 调用）。

import { initSdk } from '@/uni_modules/hans-appsflyer'

initSdk({
  devKey: 'YOUR_DEV_KEY',  // AppsFlyer 后台获取
  appId: 'idYOUR_APP_ID',  // iOS 必填，格式: id123456789
  debug: true,             // 调试模式，发布时设为 false
  enableTracking: true,    // 允许追踪
  success: (res) => {
    console.log('初始化成功:', res.appsFlyerUID)
  },
  fail: (err) => {
    console.error('初始化失败:', err.errMsg)
  }
})

追踪事件

import { trackEvent } from '@/uni_modules/hans-appsflyer'

trackEvent({
  eventName: 'af_purchase',  // 或自定义事件名
  eventValues: {
    af_revenue: 99.99,
    af_currency: 'USD',
    af_quantity: 1,
    'product_id': 'product_123'
  },
  success: (res) => {
    console.log('追踪成功:', res.eventName)
  },
  fail: (err) => {
    console.error('追踪失败:', err.errMsg)
  }
})

设置用户 ID

import { setUserId } from '@/uni_modules/hans-appsflyer'

setUserId({
  userId: 'user_123456',
  success: (res) => {
    console.log('设置成功:', res.userId)
  }
})

获取设备 ID

import { getAppsFlyerUID } from '@/uni_modules/hans-appsflyer'

getAppsFlyerUID({
  success: (res) => {
    console.log('设备 ID:', res.appsFlyerUID)
  }
})

隐私合规

import { setTrackingEnabled } from '@/uni_modules/hans-appsflyer'

// 用户同意隐私协议后开启追踪
setTrackingEnabled(true)

// 用户撤销同意时关闭追踪
setTrackingEnabled(false)

预定义常量

事件名 (AFEvent)

（uni-app / JS 侧可直接传字符串；如需常量可在业务侧自行封装。）

AFEvent.APP_OPEN               // af_app_opened
AFEvent.COMPLETE_REGISTRATION  // af_complete_registration
AFEvent.LOGIN                  // af_login
AFEvent.ADD_TO_CART            // af_add_to_cart
AFEvent.ADD_TO_WISHLIST        // af_add_to_wishlist
AFEvent.INITIATED_CHECKOUT     // af_initiated_checkout
AFEvent.PURCHASE               // af_purchase
AFEvent.CONTENT_VIEW           // af_content_view
AFEvent.SEARCH                 // af_search
AFEvent.RATE                   // af_rate
AFEvent.SHARE                  // af_share
AFEvent.INVITE                 // af_invite
AFEvent.ACHIEVEMENT_UNLOCKED   // af_achievement_unlocked
AFEvent.LEVEL_ACHIEVED         // af_level_achieved
AFEvent.SUBSCRIBE              // af_subscribe
AFEvent.START_TRIAL            // af_start_trial

参数名 (AFParam)

AFParam.REVENUE      // af_revenue
AFParam.CURRENCY     // af_currency
AFParam.QUANTITY     // af_quantity
AFParam.PRICE        // af_price
AFParam.CONTENT_ID   // af_content_id
AFParam.CONTENT_TYPE // af_content_type
AFParam.ORDER_ID     // af_order_id
AFParam.DESCRIPTION  // af_description

API 文档

initSdk(options: InitOptions)

初始化 AppsFlyer SDK

参数:

• devKey: string (必填) - AppsFlyer Dev Key
• appId: string (iOS 必填) - App Store ID，格式 id123456789
• debug: boolean (可选) - 调试模式（AppsFlyer SDK + 默认插件日志），默认 false
• enableTracking: boolean (可选) - 允许追踪，默认 true

setLogEnabled(enabled: boolean)

设置插件自身日志开关（UTS + 原生层均通过 console.* 输出到 HBuilderX 控制台）。

• 默认行为：如果你未显式调用 setLogEnabled，插件会在 initSdk 时用 options.debug 作为默认日志开关。

import { setLogEnabled } from '@/uni_modules/hans-appsflyer'

setLogEnabled(true)   // 开启插件日志
// setLogEnabled(false) // 关闭插件日志

isLogEnabled(): boolean

获取插件日志开关状态

trackEvent(options: TrackEventOptions)

追踪自定义事件

参数:

• eventName: string (必填) - 事件名称
• eventValues: UTSJSONObject (可选) - 事件参数

setUserId(options: SetUserIdOptions)

设置用户 ID，用于与业务系统关联

参数:

• userId: string (必填) - 用户唯一标识

getAppsFlyerUID(options: GetAppsFlyerUIDOptions)

获取 AppsFlyer 设备唯一标识

getAdvertisingId(options: GetAdvertisingIdOptions)

获取广告标识（归因测试用）

• Android：GAID / Advertising ID（对应 AppsFlyer Attribution test 里的 AID）
• iOS：IDFA（需 ATT 授权；未授权时可能返回空字符串）

requestTrackingAuthorization(options?: RequestTrackingAuthorizationOptions)（iOS）

请求 iOS ATT 授权（iOS 14+ 会弹系统授权弹窗）。

建议业务在“隐私弹窗/设置页面”的用户交互后调用，再调用 getAdvertisingId() 获取 IDFA。

import { requestTrackingAuthorization, getAdvertisingId } from '@/uni_modules/hans-appsflyer'

requestTrackingAuthorization({
  success: (res) => {
    console.log('ATT status:', res.status, res.statusText)
    getAdvertisingId({
      success: (idRes) => console.log('IDFA:', idRes.advertisingId),
    })
  }
})

onInitStatus(options: OnInitStatusOptions) => () => void

监听初始化结果（全局监听）。initSdk(options) 每次调用结束都会触发一次。

onAttributionData(options: OnAttributionDataOptions) => () => void（Android/iOS）

监听 AppsFlyer 转化/归因回调。建议在 initSdk() 之前先注册，以便拿到首次回调。

onDeepLink(options: OnDeepLinkOptions) => () => void（Android/iOS）

监听 DeepLink（UDL）回调。建议在 initSdk() 之前先注册。

setOneLinkId(oneLinkId: string)（Android/iOS）

设置 OneLink 模板 ID（AppsFlyer 后台获取）。

createInviteLink(options: CreateInviteLinkOptions)（Android/iOS）

生成 OneLink 邀请链接。需要先设置 setOneLinkId(oneLinkId)。

setAndroidIdCollectionEnabled(enabled: boolean)（Android）

设置是否收集 AndroidID（注意隐私合规）。

setImeiCollectionEnabled(enabled: boolean)（Android）

设置是否收集 IMEI（注意隐私合规与系统限制）。

注意：

• Android 获取 GAID 依赖 Google Play services Ads Identifier；如果你在 HBuilderX 使用“标准基座”运行，可能会出现 NoClassDefFoundError。此时需要“制作/安装自定义基座”（或做一次原生打包）让依赖进入基座后再调用本 API。
• iOS 获取 IDFA 需要 App 侧配置 NSUserTrackingUsageDescription 并调用 requestTrackingAuthorization() 请求授权（未授权时 getAdvertisingId() 可能返回空字符串）。

setTrackingEnabled(enabled: boolean)

设置是否允许追踪

错误码

常见问题

Android 运行时报 NoClassDefFoundError

通常是使用 HBuilderX “标准基座”运行导致原生依赖未进入基座。请制作/安装自定义基座（或做一次原生打包）后再验证 getAdvertisingId() / 回调监听等能力。

iOS 获取 IDFA 为空

请确保：

• App 侧已配置 NSUserTrackingUsageDescription
• 在用户交互后调用 requestTrackingAuthorization() 请求授权
• 授权未通过时 getAdvertisingId() 可能返回空字符串（属于正常情况）

归因/DeepLink 监听没有回调

建议：

• 在调用 initSdk() 之前先注册 onAttributionData() / onDeepLink()
• 按 AppsFlyer 官方文档完成 OneLink/UDL 配置，并配置 Android App Links / iOS Universal Links
• 监听函数返回的取消函数请在不需要时调用，避免重复注册

注意事项

1. Dev Key 安全: 不要在代码中硬编码 Dev Key，建议从服务器动态获取或使用配置中心
2. 调试模式: 发布前务必将 debug 设为 false（如需强制关闭插件日志，可调用 setLogEnabled(false)）
3. 隐私合规: 确保在获取用户同意后再开启追踪
4. iOS IDFA: 获取 IDFA 需要 App 侧配置 NSUserTrackingUsageDescription，并在用户交互后调用 requestTrackingAuthorization()（未授权时 getAdvertisingId() 可能返回空字符串）

相关链接

• AppsFlyer 官方文档
• uni-app x UTS 插件开发文档