更新记录

1.0.0（2026-05-11）

首次发布，提供 ATT + IDFA 广告标识符管理功能

平台兼容性

三端统一广告标识符管理插件

一个 UTS 插件搞定 iOS / Android / HarmonyOS 广告标识符获取

📋 功能概览

核心价值：

• 🎯 一次集成，三端可用 — 统一 API，统一返回结构
• 🛡️ 完整隐私合规 — iOS ATT 弹窗 + Info.plist 声明 + 鸿蒙权限
• 🔄 智能降级 — Android GAID 不可用时自动切换 OAID（覆盖 6 大厂商）
• 📦 零配置开箱即用 — uni_modules 标准插件，导入即可使用

🚀 快速开始

安装

方式一：插件市场安装（推荐）

在 HBuilderX 插件市场中搜索 csy-att-manager，点击安装。

方式二：手动安装

将 csy-att-manager 目录放入项目的 uni_modules/ 下：

your-project/
└── uni_modules/
    └── csy-att-manager/
        ├── package.json
        ├── README.md
        └── utssdk/
            ├── app-ios/
            ├── app-android/
            └── app-harmony/

基础调用

// 导入插件
const attManager = uni.requireNativePlugin('csy-att-manager')

// 获取广告标识符（三端统一）
const info = await attManager.getAdvertisingInfo()
console.log('标识符:', info.advertisingId)
console.log('类型:', info.type)        // "idfa" | "gaid" | "oaid"
console.log('平台:', info.platform)    // "ios" | "android" | "harmonyos"

iOS ATT 授权流程

// 检查当前授权状态
const status = attManager.getTrackingAuthorizationStatus()

if (status === 'notDetermined') {
  // 首次使用：弹出系统 ATT 弹窗
  const newStatus = await attManager.requestTrackingAuthorization()

  if (newStatus === 'authorized') {
    // 用户同意 → 获取 IDFA
    const info = await attManager.getAdvertisingInfo()
    sendToAnalytics(info)
  } else {
    // 用户拒绝 → 使用备选方案
    useFallbackIdentifier()
  }
}

📖 API 参考

核心 API

getAdvertisingInfo()

获取完整广告标识信息（推荐作为统一入口）。

iOS:      async → AdvertisingIdResult (需 ATT 授权后)
Android:  sync → AdvertisingIdResult
HarmonyOS: async → AdvertisingIdResult

返回值 AdvertisingIdResult：

// 示例
const info = await attManager.getAdvertisingInfo()
if (info.advertisingId.length > 0) {
  // 成功获取标识符
  uploadToServer(info.advertisingId, info.type)
} else {
  // 获取失败，使用设备指纹等备选方案
}

getAdvertisingId()

仅获取广告标识符字符串（便捷方法）。

返回值: string — 广告标识符，获取失败返回空字符串 ""

const id = attManager.getAdvertisingId()
console.log('ID:', id)  // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"

⚠️ 注意：HarmonyOS 平台此方法返回空字符串（OAID 获取是异步的），请使用 getAdvertisingInfo()。

requestTrackingAuthorization() (iOS)

弹出 iOS ATT 系统授权弹窗。

iOS:     async → ATTAuthorizationStatus
Android/HarmonyOS: sync → "notSupported"

const status = await attManager.requestTrackingAuthorization()
// status: "authorized" | "denied" | "restricted" | "notDetermined"

⚠️ 每个 App 安装周期只弹窗一次。模拟器不弹窗，须真机测试。

getTrackingAuthorizationStatus() (iOS)

获取当前 ATT 授权状态（不弹窗）。

iOS:     sync → ATTAuthorizationStatus
Android/HarmonyOS: sync → "notSupported"

扩展 API (Android)

getOaidOnly()

仅获取国内厂商 OAID（跳过 GAID）。

const oaid = attManager.getOaidOnly()  // string

已覆盖厂商：

⚙️ 平台配置

iOS

必需框架（插件自动声明）：

• AppTrackingTransparency.framework
• AdSupport.framework

隐私描述（插件自动声明）：

• NSUserTrackingUsageDescription — ATT 弹窗展示文案

Info.plist 手动追加（如需要）：

<key>NSUserTrackingUsageDescription</key>
<string>需要您的允许以提供个性化广告和内容体验。您的数据将仅用于改进服务质量，不会被出售给第三方。</string>

Android

依赖（插件自动声明）：

com.google.android.gms:play-services-ads-identifier:18.0.1

混淆规则（如需手动配置 ProGuard）：

# Google Play Services 广告ID
-keep class com.google.android.gms.ads.identifier.** { *; }
-dontwarn com.google.android.gms.ads.identifier.**

HarmonyOS

权限声明（插件自动声明）：

// module.json5
{
  "requestPermissions": [
    {
      "name": "ohos.permission.APP_TRACKING_CONSENT",
      "reason": "需要获取设备广告标识符以提供个性化内容推荐"
    }
  ]
}

🎯 典型应用场景

1. 广告归因 (Ad Attribution)

const info = await attManager.getAdvertisingInfo()

// 上报给归因平台（AppsFlyer, Adjust, 友盟 等）
attributionSDK.setDeviceId({
  idfa: info.platform === 'ios' ? info.advertisingId : undefined,
  gaid: info.type === 'gaid' ? info.advertisingId : undefined,
  oaid: info.type === 'oaid' ? info.advertisingId : undefined,
})

2. 数据分析平台

const info = await attManager.getAdvertisingInfo()

// 发送到数据平台（百度统计、腾讯分析、Firebase 等）
analytics.setUserProperty('ad_id', info.advertisingId)
analytics.setUserProperty('ad_id_type', info.type)
analytics.setUserProperty('att_status', info.attStatus)

3. 隐私合规弹窗 + 标识符获取

<template>
  <view>
    <view v-if="showConsentDialog">
      <!-- 自定义隐私弹窗 -->
      <text>我们需要使用设备标识符来提供更好的服务</text>
      <button @click="handleAgree">同意</button>
      <button @click="handleDeny">拒绝</button>
    </view>
  </view>
</template>

<script setup>
import { ref } from 'vue'

const attManager = uni.requireNativePlugin('csy-att-manager')
const showConsentDialog = ref(false)
const adId = ref('')

// 检查 ATT 状态并决定是否弹自定义弹窗
async function init() {
  // #ifdef APP-IOS
  const status = attManager.getTrackingAuthorizationStatus()
  if (status === 'notDetermined') {
    // 先弹自定义弹窗说明用途，再调用系统 ATT
    showConsentDialog.value = true
    return
  }
  // #endif
  await fetchAdId()
}

async function handleAgree() {
  showConsentDialog.value = false
  // 用户同意后弹出系统 ATT 弹窗
  await attManager.requestTrackingAuthorization()
  await fetchAdId()
}

function handleDeny() {
  showConsentDialog.value = false
  // 用户拒绝，使用脱敏方案
  useFallbackId()
}

async function fetchAdId() {
  const info = await attManager.getAdvertisingInfo()
  if (info.advertisingId) {
    adId.value = info.advertisingId
    // 初始化需要广告ID的SDK
  }
}
</script>

4. Android 国内版专享

// #ifdef APP-ANDROID
// 优先尝试 GAID，不行再用 OAID
const info = await attManager.getAdvertisingInfo()

// 或者跳过 GAID 直接拿 OAID（面向国内设备）
const oaidOnly = attManager.getOaidOnly()
if (oaidOnly.length > 0) {
  console.log('小米/华为/Oppo 设备 OAID:', oaidOnly)
}
// #endif

🔧 故障排查

📊 平台行为对照

📦 技术架构

┌─────────────────────────────────────────────┐
│              UniApp 业务层                    │
│    uni.requireNativePlugin('csy-att-manager')│
├──────────────┬──────────────┬────────────────┤
│   iOS UTS    │ Android UTS  │ HarmonyOS UTS  │
│  (Swift兼容) │ (Kotlin兼容)  │ (ArkTS兼容)    │
├──────────────┼──────────────┼────────────────┤
│  ATTracking  │ Google Play  │                │
│  Manager     │ Services     │  @kit.AdsKit   │
│      +       │     +        │  identifier    │
│  AdSupport   │ 厂商 OAID     │  .getOAID()    │
│              │ ContentPvd   │                │
├──────────────┼──────────────┼────────────────┤
│    IDFA      │ GAID │ OAID  │     OAID       │
└──────────────┴──────────────┴────────────────┘
     ATT弹窗     GMS优先        HarmonyOS
                 国内降级        3.0+

📝 更新日志

v1.0.0 (2026-05-08)

• 🎉 首次发布
• ✅ iOS: ATT 权限弹窗 + IDFA 获取
• ✅ Android: Google Advertising ID + 国内 6 厂商 OAID
• ✅ HarmonyOS: OAID 获取
• ✅ 三端统一 API

📄 许可证

MIT License © csy

💡 问题反馈：请在 DCloud 插件市场页面下方留言