更新记录

1.0.2（2026-03-19）

• 修复 Android 在页面已显示后延迟调用 initSdk() 时，start 仅使用 applicationContext 导致首个前台会话未及时建立的问题，改为优先使用当前 Activity
• 调整 Android 初始化状态判断，不再在 AppsFlyerRequestListener 未回调时提前标记成功，避免 SDK 未真正就绪时放行 trackEvent

1.0.1（2026-03-19）

• 更新 README 调用示例，统一为根入口导入，并补充显式类型写法
• 精简使用说明，保留更直接的 API 调用示例

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）

支持平台

使用方法

导入（含类型）

import {
  initSdk,
  trackEvent,
  setUserId,
  getAppsFlyerUID,
  getAdvertisingId,
  requestTrackingAuthorization,
  onInitStatus,
  onAttributionData,
  onDeepLink,
  setOneLinkId,
  createInviteLink,
  setTrackingEnabled,
  InitOptions,
  InitResult,
  TrackEventOptions,
  TrackEventResult,
  SetUserIdOptions,
  SetUserIdResult,
  GetAppsFlyerUIDOptions,
  GetAppsFlyerUIDResult,
  GetAdvertisingIdOptions,
  GetAdvertisingIdResult,
  RequestTrackingAuthorizationOptions,
  RequestTrackingAuthorizationResult,
  OnInitStatusOptions,
  OnAttributionDataOptions,
  AttributionData,
  OnDeepLinkOptions,
  DeepLinkData,
  CreateInviteLinkOptions,
  CreateInviteLinkResult,
  AppsFlyerFail,
} from '@/uni_modules/hans-appsflyer'

1. 初始化 SDK

const initOptions: InitOptions = {
  devKey: 'YOUR_DEV_KEY',
  appId: 'idYOUR_APP_ID', // iOS 必填
  debug: true,
  enableTracking: true,
  success: (res: InitResult) => {
    console.log('init success', res.appsFlyerUID)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('init fail', err.errMsg)
  },
}

initSdk(initOptions)

2. 注册监听

建议在 initSdk() 之前注册。

const initStatusOptions: OnInitStatusOptions = {
  onSuccess: (res: InitResult) => {
    console.log('onInitStatus', res.appsFlyerUID)
  },
}

const attributionOptions: OnAttributionDataOptions = {
  onData: (data: AttributionData) => {
    console.log('attribution', data)
  },
}

const deepLinkOptions: OnDeepLinkOptions = {
  onDeepLink: (data: DeepLinkData) => {
    console.log('deepLink', data)
  },
}

const stopInitStatus: () => void = onInitStatus(initStatusOptions)
const stopAttributionData: () => void = onAttributionData(attributionOptions)
const stopDeepLink: () => void = onDeepLink(deepLinkOptions)

// 不再需要时取消监听
// stopInitStatus()
// stopAttributionData()
// stopDeepLink()

3. 追踪事件

const trackEventOptions: TrackEventOptions = {
  eventName: 'af_purchase',
  eventValues: {
    af_revenue: 99.99,
    af_currency: 'USD',
    af_quantity: 1,
    product_id: 'product_123',
  },
  success: (res: TrackEventResult) => {
    console.log('track success', res.eventName)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('track fail', err.errMsg)
  },
}

trackEvent(trackEventOptions)

4. 设置用户 ID

const setUserIdOptions: SetUserIdOptions = {
  userId: 'user_123456',
  success: (res: SetUserIdResult) => {
    console.log('setUserId success', res.userId)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('setUserId fail', err.errMsg)
  },
}

setUserId(setUserIdOptions)

5. 获取设备 ID

const getUIDOptions: GetAppsFlyerUIDOptions = {
  success: (res: GetAppsFlyerUIDResult) => {
    console.log('appsFlyerUID', res.appsFlyerUID)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('getAppsFlyerUID fail', err.errMsg)
  },
}

getAppsFlyerUID(getUIDOptions)

6. 请求 ATT 并获取广告标识（iOS）

const getAdvertisingIdOptions: GetAdvertisingIdOptions = {
  success: (res: GetAdvertisingIdResult) => {
    console.log('advertisingId', res.advertisingId)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('getAdvertisingId fail', err.errMsg)
  },
}

const requestTrackingAuthorizationOptions: RequestTrackingAuthorizationOptions = {
  success: (res: RequestTrackingAuthorizationResult) => {
    console.log('ATT status', res.status, res.statusText)
    getAdvertisingId(getAdvertisingIdOptions)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('requestTrackingAuthorization fail', err.errMsg)
  },
}

requestTrackingAuthorization(requestTrackingAuthorizationOptions)

7. OneLink 邀请链接

setOneLinkId('YOUR_ONELINK_ID')

const createInviteLinkOptions: CreateInviteLinkOptions = {
  channel: 'test',
  customerId: 'user_123',
  success: (res: CreateInviteLinkResult) => {
    console.log('inviteLink', res.inviteLink)
  },
  fail: (err: AppsFlyerFail) => {
    console.error('createInviteLink fail', err.errMsg)
  },
}

createInviteLink(createInviteLinkOptions)

8. 隐私合规开关

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

• Android：如果是在页面已显示后才调用 initSdk()（例如用户同意隐私后再初始化），插件会优先使用当前 Activity 调用 AppsFlyerLib.start(...)；建议仍在页面可见时调用。

参数:

• 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 作为默认日志开关。

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+ 会弹系统授权弹窗）。

建议在用户交互之后调用；如果需要 IDFA，通常顺序是先 requestTrackingAuthorization()，再 getAdvertisingId()。

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

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

可直接参考上文“2. 注册监听”。

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

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

可直接参考上文“2. 注册监听”。

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

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

可直接参考上文“2. 注册监听”。

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
• 监听函数返回的取消函数请在不需要时调用，避免重复注册

Android 初始化后要切后台再回来才有回调

请确认：

• 使用包含此修复的插件版本；Android 侧会优先使用当前 Activity 调用 AppsFlyerLib.start(...)
• 尽量在页面已可见、当前存在 Activity 的时机调用 initSdk()
• trackEvent() 请等待 initSdk() 的 success 或 onInitStatus.onSuccess 后再调用

注意事项

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

相关链接

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