GoogleAdsOnDeviceConversion 库的作用与用法

GoogleAdsOnDeviceConversion 库详细报告

1. 概述

GoogleAdsOnDeviceConversion 是一个专为 iOS 应用设计的软件开发工具包（SDK），用于实现设备端转换测量（On-Device Conversion Measurement）。它的核心功能是帮助开发者在用户设备上直接收集和处理广告转换数据（如应用安装、重新安装等），以支持隐私保护的广告效果归因。该库特别适用于无法直接集成 Google Analytics for Firebase (GA4F) 的场景，或者需要独立 SDK 的情况。

1.1 主要作用

隐私保护：通过在设备端处理转换数据，减少敏感数据传输，符合严格的隐私法规（如 GDPR）。
独立性：提供独立于 Firebase 的解决方案，适合多样化的开发需求。
广告效果优化：帮助广告主了解 iOS 应用广告的效果，优化营销策略。

1.2 适用场景

iOS 应用开发者希望在保护用户隐私的同时，测量广告转换效果。
无法或不愿使用 Google Analytics for Firebase 的项目。
需要与第三方归因平台（如 Adjust）集成的场景。

2. 集成方式

GoogleAdsOnDeviceConversion 支持通过 CocoaPods 和 Swift Package Manager 集成。以下是详细步骤：

2.1 使用 CocoaPods

打开项目的 Podfile，添加以下行：
ruby 复制代码
```
pod 'GoogleAdsOnDeviceConversion'
```
在终端中运行以下命令：
bash 复制代码
```
pod install --repo-update
```

2.2 使用 Swift Package Manager

在 Xcode 中，点击 File > Add Packages。

在搜索栏输入以下 GitHub 仓库 URL：

vbnet 复制代码

https://github.com/googleads/google-ads-on-device-conversion-ios-sdk

选择版本（建议选择 "Up to Next Major Version"），然后点击 Add Package。
Xcode 将自动解析并下载依赖项。

2.3 注意事项

如果您的应用使用 Firebase Analytics 11.14.0 或更高版本，GoogleAdsOnDeviceConversion 可能已自动包含，无需手动添加。
确保您的 Xcode 版本为 16.0 或更高，目标 iOS 版本为 12.0 或更高。

3. 使用方法

以下是如何在 Swift 中使用 GoogleAdsOnDeviceConversion 的详细步骤。

3.1 Swift 中的使用

在 Swift 项目中，您需要执行以下步骤：

3.1.1 导入库

在需要使用该库的 Swift 文件顶部添加：

swift 复制代码

import GoogleAdsOnDeviceConversion

3.1.2 设置首次启动时间

在应用启动时（例如，在 AppDelegate 或 SceneDelegate 的 application(_:didFinishLaunchingWithOptions:) 方法中），设置应用的首次启动时间：

swift 复制代码

ConversionManager.sharedInstance.setFirstLaunchTime(Date())

此步骤对于准确的转换归因至关重要。

3.1.3 获取转换信息

使用以下方法获取聚合的转换信息，通常用于应用安装（.installation）：

swift 复制代码

ConversionManager.sharedInstance.fetchAggregateConversionInfo(for: .installation) { aggregateConversionInfo, error in
    if let info = aggregateConversionInfo {
        // 使用 aggregateConversionInfo，例如作为 odm_info 参数
        print("Aggregate Conversion Info: \(info)")
    } else if let error = error {
        print("Error fetching conversion info: \(error)")
    }
}

aggregateConversionInfo 是一个字符串（例如 "abcdEfadGdaf"），可作为 odm_info 查询参数传递给广告平台。

3.3 示例代码

以下是一个完整的 Swift 示例，展示如何在应用启动时设置和获取转换信息：

swift 复制代码

import UIKit
import GoogleAdsOnDeviceConversion

@UIApplicationMain
class AppDelegate: UIResponder, UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        // 设置首次启动时间
        ConversionManager.sharedInstance.setFirstLaunchTime(Date())
        
        // 获取转换信息
        ConversionManager.sharedInstance.fetchAggregateConversionInfo(for: .installation) { aggregateConversionInfo, error in
            if let info = aggregateConversionInfo {
                print("Aggregate Conversion Info: \(info)")
                // 示例：将 info 传递给广告平台
                // let url = URL(string: "https://your-ad-platform.com?odm_info=\(info)")!
            } else if let error = error {
                print("Error: \(error.localizedDescription)")
            }
        }
        return true
    }
}

4. 与其他 SDK 的集成

4.1 与 Firebase Analytics

如果您的应用使用 Firebase Analytics 11.14.0 或更高版本，GoogleAdsOnDeviceConversion 可能已自动包含，无需手动添加。
若需手动集成，确保 Podfile 中未重复添加依赖。

4.2 与 Adjust SDK

如果您使用 Adjust SDK 进行归因，可以通过 Adjust 的 ODM 插件启用设备端转换测量：

在 Podfile 中添加：

ruby 复制代码

pod 'Adjust/AdjustGoogleOdm'
pod 'GoogleAdsOnDeviceConversion', '2.0.0'

在应用启动时尽早调用 Adjust SDK 的 initSdk 方法，例如：

swift 复制代码

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Adjust.initSdk(with: yourConfig)
    return true
}

如果需要延迟 SDK 初始化，可使用 Adjust 的 First Session Delay 功能。
Adjust SDK 会自动处理首次启动时间捕获，确保归因准确。

5. 注意事项

以下是使用 GoogleAdsOnDeviceConversion 时需要注意的关键点：

方面	细节
首次启动时间	确保 `setFirstLaunchTime()` 设置的日期是应用的实际首次启动时间，否则可能影响归因准确性。
地域限制	该功能在欧洲经济区（EEA）、英国和瑞士不可用（参考 Google Ads Help）。
Firebase 集成	使用 Firebase Analytics 11.14.0 或更高版本时，无需手动添加此库。
版本兼容性	Adjust SDK 已测试版本 2.0.0 的 `GoogleAdsOnDeviceConversion`，建议验证新版本的兼容性。
隐私合规性	确保您的应用披露如何使用 Google 服务处理数据（参考 Google Ads 隐私披露）。

6. 总结

GoogleAdsOnDeviceConversion 库是 iOS 应用开发者精确衡量 Google Ads 广告系列带来的应用安装和后续应用内操作的关键工具。其主要目标是在严格遵守用户隐私标准的前提下，增强广告系列的优化和报告能力。

从功能上看，它是一个"设备端转化衡量插件"，旨在与 Firebase Analytics SDK 和 Google 的应用归因合作伙伴 (AAP) SDK 协同工作。这种集成表明它并非一个独立的广告 SDK，而是一个专门的实用工具，用于在更广泛的 Google Ads 和 Firebase 生态系统中提高转化数据的精确度。

该库在设计上持续强调"隐私保护" ，并特别提及"去标识化的临时信号" 。这表明 Google 正在对不断变化的隐私法规（如通用数据保护条例 (GDPR)）和平台级变化（如 Apple 的应用跟踪透明度 (ATT) 框架）做出战略性和前瞻性的调整。通过在用户设备上直接进行归因，而无需将可识别的个人数据传输到设备之外，Google 旨在提供强大而有效的衡量能力，这些能力本身就符合现代隐私期望。这种方法将该库定位为在隐私受限环境中保持广告有效性的必要适应。