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

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

简介： 衡量 iOS Ads 转化

第 1 步： 实现登录体验

第 2 步：集成 Google Analytics

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

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

现在，您可以收集用户的电子邮件地址和电话号码，并且您的应用 已包含 Google Analytics for Firebase SDK，因此您可以使用这两者开始 衡量转化。

调用 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 的最佳实践

为确保准确且持续地进行设备端转化衡量，请执行以下任一操作：

在每次应用更新时调用（推荐）

Google Analytics for Firebase SDK 12.1.0 及更高版本对设备端转化衡量进行了 改进。为确保这些改进适用于所有用户（包括在应用更新之前已登录的用户），请务必在应用更新后再次调用 initiateOnDeviceConversionMeasurement API。

具体来说，在您的应用更新到 SDK 12.1.0 版本之前登录的用户不会纳入增强型衡量范围，除非您再次为他们调用 initiateOnDeviceConversionMeasurement API。如果不进行应用更新检查，只有当用户退出账号并重新登录时，才会发生这种情况。

最佳实践是，至少为每个应用版本的已登录用户调用一次 API。您可以在应用启动时实现检查，以便仅在应用版本自上次调用以来发生更改时调用 API。

Swift

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
let cachedAppVersion = UserDefaults.standard.string(forKey: "cachedAppVersion")
let currentAppVersion =
  Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String

if cachedAppVersion != currentAppVersion {
let hashedEmailAddress = ...
Analytics.initiateOnDeviceConversionMeasurement(hashedEmailAddress: hashedEmailAddress)
UserDefaults.standard.set(currentAppVersion, forKey: "cachedAppVersion")
}

Objective-C

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
NSString *cachedAppVersion =
  [[NSUserDefaults standardUserDefaults] stringForKey:@"cachedAppVersion"];
NSString *currentAppVersion = [[NSBundle mainBundle]
  objectForInfoDictionaryKey:@"CFBundleShortVersionString"];

if (![cachedAppVersion isEqualToString:currentAppVersion]) {
NSString *hashedEmailAddress = ...
[FIRAnalytics initiateOnDeviceConversionMeasurementWithHashedEmailAddress:hashedEmailAddress];
[[NSUserDefaults standardUserDefaults] setObject:currentAppVersion
                                          forKey:@"cachedAppVersion"];
}

Unity

// On app launch if the app version has changed, call the API with the first-party data
// (for example: email address, phone number, hashed email address, hashed phone number).
string cachedAppVersion = PlayerPrefs.GetString("cached_app_version", "");
string currentAppVersion = Application.version;

if (cachedAppVersion != currentAppVersion) {
byte[] hashedEmailAddress = ...
FirebaseAnalytics.InitiateOnDeviceConversionMeasurementWithHashedEmailAddress(
    hashedEmailAddress);
PlayerPrefs.SetString("cached_app_version", currentAppVersion);
PlayerPrefs.Save();
}

在登录后立即调用

请务必在用户成功登录或注册其电子邮件地址或电话号码后立即调用 initiateOnDeviceConversionMeasurement API。

新注册的时间考虑因素

如果用户注册后立即发生关键转化事件（并且您调用了 API），请考虑在 API 调用和记录关键事件之间实现一个较短的延迟（例如 5 秒）。这有助于确保在记录事件之前完全初始化设备端衡量。

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

该 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]

对于电话号码，在通过 SHA256 进行哈希处理之前，号码必须已采用 E.164 格式（即 以 + 开头，国家/地区代码为 1-3 位数，订阅者号码最多为 12 位数 ）。

请注意，经过哈希处理的 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 调试控制台中显示类似于以下日志消息的消息：

[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 步：排查和处理常见问题

---