NLDClient-yudde/Tool/sdk_packages/DeviceHelper_iOS/README.md

DeviceHelper_iOS

Unity iOS 原生桥接插件，提供以下功能：

1. IDFA — 广告标识符（异步获取，含自动弹窗机制）
2. IDFV — 供应商标识符（同步获取）
3. CAID 设备信息采集 — 采集 iOS 设备信息，以 JSON 字符串形式返回给 Unity C#

---

文件说明

文件	路径
源文件	Assets/Plugins/iOS/DeviceIdentifiers.m
C# 桥接	项目 Assets/PhxhSDK/Phxh/Others/DeviceHelper.cs

---

Unity C# 调用方式

1. 获取 IDFA（异步）

// IDFA 为异步获取，结果会通过 UnitySendMessage 回调到 GameLauncher.OnIDFAResult
// 主动触发请求：
// （代码中已实现 App 启动时自动弹窗，无需额外调用）
// 若需手动调用：
// （在 iOS 原生侧已暴露 RequestIDFA() 函数，可通过 DllImport 调用）

回调方式：结果通过 UnitySendMessage("GameLauncher", "OnIDFAResult", idfaString) 发送。 确保 Unity 场景中存在名为 GameLauncher 的 GameObject，并挂载了 OnIDFAResult(string idfa) 方法。

2. 获取 IDFV（同步）

using System.Runtime.InteropServices;

public static string GetIDFV()
{
#if UNITY_IOS && !UNITY_EDITOR
    IntPtr ptr = GetIDFVNative();
    string result = Marshal.PtrToStringAuto(ptr);
    Marshal.FreeCoTaskMem(ptr);
    return result;
#else
    return "";
#endif
}

#if UNITY_IOS && !UNITY_EDITOR
[DllImport("__Internal", EntryPoint = "GetIDFV")]
private static extern IntPtr GetIDFVNative();
#endif

3. 获取 CAID 设备信息 JSON（同步）

// 直接调用 DeviceHelper.GetCAIDDeviceInfoJSON()
// 返回 JSON 字符串，包含 CAID API 所需的全部设备参数
string caidJson = DeviceHelper.GetCAIDDeviceInfoJSON();

返回的 JSON 示例：

{
  "bootTimeInSec": "1595643553",
  "countryCode": "CN",
  "language": "zh-Hans-CN",
  "deviceName": "e910dddb2748c36b47fcde5dd720eec1",
  "systemVersion": "14.0",
  "machine": "iPhone10,3",
  "carrierInfo": "中国移动",
  "memory": "3955589120",
  "disk": "63900340224",
  "sysFileTime": "1595214620.383940",
  "model": "D22AP",
  "timeZone": "28800",
  "deviceInitTime": "1632467920.301150749"
}

各字段说明参见 CAID API 接入文档 附录 6.1 章节。

C# 侧方法定义（已内置在 DeviceHelper.cs 中）

public static string GetCAIDDeviceInfoJSON()
{
#if UNITY_IOS && !UNITY_EDITOR
    IntPtr ptr = GetCAIDDeviceInfoJSONNative();
    if (ptr == IntPtr.Zero)
        return "{}";
    string result = Marshal.PtrToStringAuto(ptr);
    Marshal.FreeCoTaskMem(ptr);
    return result ?? "{}";
#else
    return "{}";
#endif
}

#if UNITY_IOS && !UNITY_EDITOR
[DllImport("__Internal", EntryPoint = "GetCAIDDeviceInfoJSON")]
private static extern IntPtr GetCAIDDeviceInfoJSONNative();
#endif

---

注意点

IDFA

• 授权弹窗：获取 IDFA 必须调起 iOS 系统原生的 AppTrackingTransparency 弹窗，只有在用户主动允许追踪后才可获取真实 IDFA。
• 异步回调：由于需要等待用户交互，此过程为异步操作。
• 回调目标：获取结果会通过 UnitySendMessage 传递给 Unity。请务必确保 Unity 场景中存在名为 GameLauncher 的 GameObject，并已挂载接收回调的方法。

IDFV

• 直接获取：IDFV 为设备厂商 ID，无需经过用户授权弹窗，可直接在调用时同步获取并返回结果。

CAID 设备信息

• 同步接口：所有设备参数的采集均在当前线程同步完成，返回 JSON 字符串。
• 注意内存释放：C# 侧在 Marshal.PtrToStringAuto 后调用 Marshal.FreeCoTaskMem 释放原生侧 malloc 分配的内存。

自动触发机制（IDFA 弹窗）

• 默认行为：代码内实现了 onAppDidBecomeActive 监听。App 每次启动并进入活跃状态时，将自动调起 IDFA 请求弹窗。
• 修改建议：若项目业务逻辑不需要在 App 刚启动时就弹出授权框（例如需要延迟到特定关卡或场景再弹），请在源码中手动删除或注释掉 AutoIDFATrigger 相关的 +load 与 onAppDidBecomeActive 实现。

---

Xcode 工程配置须知（重要）

• 添加系统库： 在 Xcode -> Target -> Build Phases -> Link Binary With Libraries 中，添加以下框架：

  框架	用途
  AdSupport.framework	IDFA 获取
  AppTrackingTransparency.framework	跟踪授权弹窗
  CoreTelephony.framework	运营商信息采集（CAID）
  libz.tbd	MD5 计算（CAID）

• 配置隐私描述： 在 Info.plist 中必须添加跟踪权限的用途描述，否则弹窗无法显示且会导致应用崩溃或拒审：

  • Key: Privacy - Tracking Usage Description (NSUserTrackingUsageDescription)
  • Value: 请填写向用户解释为何需要追踪的文案（如"用于提供个性化广告服务"）

• Unity 构建时自动添加框架： 若使用 Unity 2020.3+，可在 Player Settings -> iOS -> Other Settings 中勾选：

  • AdSupport.framework → Required
  • AppTrackingTransparency.framework → Required
  • CoreTelephony.framework → Required

  或在项目中添加 TDS-Info.plist 等相关配置（Assets/Plugins/iOS/TDS-Info.plist）。

---

版本历史

版本	日期	说明
1.0.0	-	初始版本：IDFA / IDFV 获取 + 自动弹窗 + CAID 设备信息采集