教程：衡量 iOS 广告转化情况

第 3 步：使用 Google Analytics 启动设备端转化衡量

简介：衡量 iOS Ads 转化

第 1 步： 实现登录体验

第 2 步：集成 Google Analytics

第 3 步：使用 Google Analytics 发起设备端转化衡量

第 4 步： 排查和处理常见问题

现在，您可以收集用户的电子邮件地址和电话号码，并且您的应用已集成 Firebase SDK 的 Google Analytics，接下来就可以使用这两项功能开始衡量转化了。

调用 API

使用第 1 步中获得用户同意的电子邮件地址或电话号码调用转化衡量 API，该地址或号码用于衡量广告转化，且不会允许任何个人身份信息离开用户设备。

您可以通过以下两种方式启动衡量：

• 使用凭据
• 使用经过哈希处理的凭据

使用电子邮件地址或电话号码

Swift

导入 FirebaseAnalytics 模块，并将电子邮件地址或电话号码传入 initiateOnDeviceConversionMeasurement() API。

注意 ：系统可能会依序调用 initiateOnDeviceConversionMeasurement(emailAddress:) 和 initiateOnDeviceConversionMeasurement(phoneNumber:) 方法，但每个用户只能报告一次匹配。如果与任一 API 匹配，系统会有效地忽略后续的 API 调用。

import FirebaseAnalytics

// ...
// If you're using an email address....
Analytics.initiateOnDeviceConversionMeasurement(emailAddress: "[e-mail]")
// If you're using a phone number....
Analytics.initiateOnDeviceConversionMeasurement(phoneNumber: "[phone]")

Objective-C

导入 FirebaseAnalytics 模块，并将电子邮件地址传递给 initiateOnDeviceConversionMeasurementWithEmailAddress: API，或将电话号码传递给 initiateOnDeviceConversionMeasurementWithPhoneNumber: API。

注意 ：系统可能会依序调用 initiateOnDeviceConversionMeasurementWithEmailAddress: 和 initiateOnDeviceConversionMeasurementWithPhoneNumber: 方法，但每个用户只能报告一次匹配。如果与任一 API 匹配，系统会有效地忽略后续的 API 调用。

@import FirebaseAnalytics;

// ...
// If you're using an email address....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:@"[e-mail]"];
// If you're using a phone number....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:@"[phone]"];

Unity

导入 Firebase.Analytics 命名空间，并将电子邮件地址传递给 InitiateOnDeviceConversionMeasurementWithEmailAddress() API，或将电话号码传递给 InitiateOnDeviceConversionMeasurementWithPhoneNumber() API：

注意 ：系统可能会依序调用 InitiateOnDeviceConversionMeasurementWithEmailAddress() 和 InitiateOnDeviceConversionMeasurementWithPhoneNumber() 方法，但每个用户只能报告一次匹配。如果与任一 API 匹配，系统会有效地忽略后续的 API 调用。

using Firebase.Analytics;

// ...
// If you're using an email address....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithEmailAddress("[e-mail]");
// If you're using a phone number....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithPhoneNumber("[phone]");

注意：最佳实践是每次安装调用一次 API，并且尽可能在用户注册电子邮件地址或电话号码后立即调用。

重要提示：请注意，如果用户注册电子邮件地址或电话号码后立即发生预期的应用内操作或事件，请考虑在发起设备端转化衡量和记录事件之间实现一小段延迟时间。

使用经过哈希处理的电子邮件地址或电话号码

该 API 接受使用 SHA256 算法对电子邮件地址和电话号码进行哈希处理。您可以在调用 SDK 之前在代码中执行哈希处理，以便保持对用户数据的控制。

如需使用经过哈希处理的凭据，请对地址和电话号码进行标准化，然后使用 SHA256 对其进行哈希处理，最后调用 API。

对电子邮件地址和电话号码进行规范化

对于电子邮件地址，Google Analytics API 假定在应用 SHA256 之前会执行特定的标准化处理，因此请按照以下步骤对数据进行标准化处理：

1. 将整个电子邮件地址转换为小写形式。

2. 如果电子邮件地址以域名 @googlemail.com 结尾，请将 @googlemail.com 域名替换为 @gmail.com。

3. 对于以域名 @gmail.com 结尾的地址（包括在上一步中修改的地址）：

   1. 从用户名部分中移除所有句点。

   2. 在用户名部分进行以下替换：

      • 将字母 I、i 或数字 1 替换为字母 l
      • 将数字 0 替换为字母 o
      • 将数字 2 替换为字母 z
      • 将数字 5 替换为字母 s

例如，标准化后：

• [e-mail] 变为 [e-mail]
• [e-mail] 变为 [e-mail]

对于电话号码，必须先采用 E.164 格式（即前缀为“+”，国家/地区代码为 1-3 位数，用户号码最多为 12 位数），然后才能使用 SHA256 进行哈希处理。

请注意，经过 SHA256 哈希处理的电子邮件地址或电话号码必须为 32 个字节长，并且不是十六进制字符串。

使用经过哈希处理的凭据调用 API

Swift

导入 FirebaseAnalytics 模块，并将电子邮件地址或电话号码传入 initiateOnDeviceConversionMeasurement() API。

注意 ：系统可能会依序调用 initiateOnDeviceConversionMeasurement(hashedEmailAddress:) 和 initiateOnDeviceConversionMeasurement(hashedPhoneNumber:) 方法，但每个用户只能报告一次匹配。如果找到与任一 API 匹配的值，系统会有效地忽略后续的 API 调用。

import FirebaseAnalytics

// ...
// If you're using an email address....
Analytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress: hashedEmailAddress)
// If you're using a phone number....
Analytics.initiateOnDeviceConversionMeasurement(hashedPhoneNumber: hashedPhoneNumber)

Objective-C

导入 FirebaseAnalytics 模块，并将电子邮件地址传递给 initiateOnDeviceConversionMeasurementWithHashedEmailAddress: API，或将电话号码传递给 initiateOnDeviceConversionMeasurementWithHashedPhoneNumber: API。

注意 ：系统可能会依序调用 initiateOnDeviceConversionMeasurementWithHashedEmailAddress: 和 initiateOnDeviceConversionMeasurementWithHashedPhoneNumber: 方法，但每个用户只能报告一次匹配。如果找到与任一 API 匹配的值，系统会有效地忽略后续的 API 调用。

@import FirebaseAnalytics;

// ...
// If you're using an email address....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];
// If you're using a phone number....
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedPhoneNumber:hashedPhoneNumber];

Unity

导入 Firebase.Analytics 命名空间，并将电子邮件地址传入 InitiateOnDeviceConversionMeasurementWithHashedEmailAddress() API，或将电话号码传入 InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber() API：

注意 ：系统可能会依序调用 InitiateOnDeviceConversionMeasurementWithHashedEmailAddress() 和 InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber() 方法，但每个用户只能报告一次匹配。如果找到任何 API 的匹配项，系统会有效地忽略后续的 API 调用。

using Firebase.Analytics;

// ...
// If you're using an email address....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(hashedEmailAddress);
// If you're using a phone number....
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber(hashedPhoneNumber);

注意：最佳实践是每次安装调用一次 API，并且尽可能在用户注册电子邮件地址或电话号码后立即调用。

重要提示：请注意，如果用户注册电子邮件地址或电话号码后立即发生预期的应用内操作或事件，请考虑在发起设备端转化衡量和记录事件之间实现一小段延迟时间。

使用 Xcode 调试日志进行验证（可选）

如果您启用了调试模式，请确保在调用 initiateMeasurement API 后，Xcode 调试控制台中显示如下日志消息：

[FirebaseAnalytics][I-ACS023225] Initiated on-device conversion measurement

如果您启用了调试模式并添加了 -DebugOnDeviceConversionMeasurement 启动参数，则调用 initiateOnDeviceConversionMeasurement() API 将模拟匹配。

[FirebaseAnalytics][I-ACS023229] On-device conversion measurement found a match

---

第 2 步：集成 Google Analytics 第 4 步：排查和处理常见问题

---