Tutorial: Measure iOS Ads conversions

Step 3: Initiate on-device conversion measurement using Google Analytics

Introduction: Measure iOS Ads conversions

Step 1: Implement a sign-in experience

Step 2: Integrate Google Analytics

Step 3: Initiate on-device conversion measurement using Google Analytics

Step 4: Troubleshoot and handle common issues

Now that you can collect users' email addresses and phone numbers and your app has the Google Analytics for Firebase SDK, you can use the two to start measuring conversions.

Call the API

Call the conversion measurement API with the consented email address or phone number from Step 1, which is used for ads conversion measurement, without allowing any personally identifiable information to leave the user device.

There are two ways to initiate measurement:

• Using credentials
• Using hashed credentials

Use email address or phone number

Swift

Import the FirebaseAnalytics module and pass in the email address or phone number to the initiateOnDeviceConversionMeasurement() API.

Note: The initiateOnDeviceConversionMeasurement(emailAddress:) and initiateOnDeviceConversionMeasurement(phoneNumber:) methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

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

Import the FirebaseAnalytics module and pass in the email address to the initiateOnDeviceConversionMeasurementWithEmailAddress: API or the phone number to the initiateOnDeviceConversionMeasurementWithPhoneNumber: API.

Note: The initiateOnDeviceConversionMeasurementWithEmailAddress: and initiateOnDeviceConversionMeasurementWithPhoneNumber: methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

@import FirebaseAnalytics;

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

Unity

Import the Firebase.Analytics namespace and pass in the email address to the InitiateOnDeviceConversionMeasurementWithEmailAddress() API or the phone number to the InitiateOnDeviceConversionMeasurementWithPhoneNumber() API:

Note: The InitiateOnDeviceConversionMeasurementWithEmailAddress() and InitiateOnDeviceConversionMeasurementWithPhoneNumber() methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

using Firebase.Analytics;

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

Note: Email and phone number matching only need to occur once per install on the device, and matching ideally occurs as close as possible to login.

Important: Be aware that if an intended in-app action or event happens immediately after a user email or phone registration, consider implementing a small time delay between initiating on-device conversion measurement and logging the event.

Use a hashed email address or phone number

The API will accept email addresses and phone numbers hashed with SHA256. You can maintain control of your user's data by performing the hashing in your code before making calls to the SDK.

To use hashed credentials, normalize addresses and numbers, hash them with SHA256, then call the API.

Normalize email addresses and phone numbers

For email addresses, the Google Analytics API assumes that a particular normalization is performed before SHA256 is applied, so follow these steps to normalize your data:

1. Convert the entire email address to lowercase.

2. If the email address ends in domain @googlemail.com, replace the @googlemail.com domain with @gmail.com.

3. For addresses ending in domain @gmail.com (including those modified in the previous step):

   1. Remove all periods from the username portion.

   2. Make the following substitutions in the username portion:

      • For letters I or i, or digit 1, substitute letter l
      • For digit 0, substitute letter o
      • For digit 2, substitute letter z
      • For digit 5, substitute letter s

For example, after normalization:

• [e-mail] becomes [e-mail]
• [e-mail] becomes [e-mail]

For phone numbers, numbers must already be in E.164 format (that is, prefix with +, 1-3 digits for country code, max 12 digits for subscriber number) prior to hashing with SHA256.

Call the API with hashed credentials

Swift

Import the FirebaseAnalytics module and pass in the email address or phone number to the initiateOnDeviceConversionMeasurement() API.

Note: The initiateOnDeviceConversionMeasurement(hashedEmailAddress:) and initiateOnDeviceConversionMeasurement(hashedPhoneNumber:) methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

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

Import the FirebaseAnalytics module and pass in the email address to the initiateOnDeviceConversionMeasurementWithHashedEmailAddress: API or the phone number to the initiateOnDeviceConversionMeasurementWithHashedPhoneNumber: API.

Note: The initiateOnDeviceConversionMeasurementWithHashedEmailAddress: and initiateOnDeviceConversionMeasurementWithHashedPhoneNumber: methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

@import FirebaseAnalytics;

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

Unity

Import the Firebase.Analytics namespace and pass in the email address to the InitiateOnDeviceConversionMeasurementWithHashedEmailAddress() API or the phone number to the InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber() API:

Note: The InitiateOnDeviceConversionMeasurementWithHashedEmailAddress() and InitiateOnDeviceConversionMeasurementWithHashedPhoneNumber() methods may be called sequentially, but only one match can be reported per user. If a match is found with either API, then subsequent API call are effectively ignored.

using Firebase.Analytics;

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

Note: Email and phone number matching only need to occur once per install on the device, and matching ideally occurs as close as possible to login.

Important: Be aware that if an intended in-app action or event happens immediately after a user email or phone registration, consider implementing a small time delay between initiating on-device conversion measurement and logging the event.

Verify with Xcode debug logs (optional)

If you enabled debug mode, after calling the initiate measurement API, ensure that a message like the following log message appears in the Xcode debug console:

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

In Firebase 9.6.0 or later, if you enabled debug mode and included the -DebugOnDeviceConversionMeasurement launch argument, then calling the initiateOnDeviceConversionMeasurement() API will simulate a match.

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

---

Step 2: Integrate Google Analytics Step 4: Troubleshoot and handle common issues

---