Add Analytics function for on-device conversion (#1429)

* Add Analytics function for phone number conversion

* Formatting

* Update analytics.h

* Update analytics_test.cc

Author: a-maurice

analytics/integration_test/src/integration_test.cc

@@ -190,6 +190,8 @@ TEST_F(FirebaseAnalyticsTest, TestSetProperties) {
   // Initiate on-device conversion measurement.
   firebase::analytics::InitiateOnDeviceConversionMeasurementWithEmailAddress(
       "my_email@site.com");
+  firebase::analytics::InitiateOnDeviceConversionMeasurementWithPhoneNumber(
+      "+15551234567");
 }
 
 TEST_F(FirebaseAnalyticsTest, TestLogEvents) {

analytics/src/analytics_android.cc

@@ -411,6 +411,16 @@ void InitiateOnDeviceConversionMeasurementWithEmailAddress(
   // No-op on Android
 }
 
+/// Initiates on-device conversion measurement given a phone number on iOS
+/// (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+void InitiateOnDeviceConversionMeasurementWithPhoneNumber(
+    const char* phone_number) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  // No-op on Android
+}
+
 // Set a user property to the given value.
 void SetUserProperty(const char* name, const char* value) {
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());

analytics/src/analytics_ios.mm

@@ -266,6 +266,14 @@ void InitiateOnDeviceConversionMeasurementWithEmailAddress(const char* email_add
   [FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:@(email_address)];
 }
 
+/// Initiates on-device conversion measurement given a phone number on iOS (no-op on
+/// Android). On iOS, requires dependency GoogleAppMeasurementOnDeviceConversion to be linked
+/// in, otherwise it is a no-op.
+void InitiateOnDeviceConversionMeasurementWithPhoneNumber(const char* phone_number) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  [FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:@(phone_number)];
+}
+
 // Set a user property to the given value.
 void SetUserProperty(const char* name, const char* value) {
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());

analytics/src/analytics_stub.cc

@@ -106,6 +106,15 @@ void InitiateOnDeviceConversionMeasurementWithEmailAddress(
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
 }
 
+/// Initiates on-device conversion measurement given a phone number on iOS
+/// (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+void InitiateOnDeviceConversionMeasurementWithPhoneNumber(
+    const char* phone_number) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+}
+
 // Set a user property to the given value.
 void SetUserProperty(const char* /*name*/, const char* /*value*/) {
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());

analytics/src/include/firebase/analytics.h

@@ -487,6 +487,17 @@ void LogEvent(const char* name, const Parameter* parameters,
 void InitiateOnDeviceConversionMeasurementWithEmailAddress(
     const char* email_address);
 
+/// Initiates on-device conversion measurement given a phone number in E.164
+/// format on iOS (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+/// @param phone_number User phone number. Must be in E.164 format, which means
+/// it must be
+///   limited to a maximum of 15 digits and must include a plus sign (+) prefix
+///   and country code with no dashes, parentheses, or spaces.
+void InitiateOnDeviceConversionMeasurementWithPhoneNumber(
+    const char* phone_number);
+
 /// @brief Set a user property to the given value.
 ///
 /// Properties associated with a user allow a developer to segment users

analytics/src_ios/fake/FIRAnalytics.h

@@ -23,6 +23,8 @@
 
 + (void)initiateOnDeviceConversionMeasurementWithEmailAddress:(nonnull NSString *)emailAddress;
 
++ (void)InitiateOnDeviceConversionMeasurementWithPhoneNumber:(nonnull NSString *)phoneNumber;
+
 + (void)setUserPropertyString:(nullable NSString *)value forName:(nonnull NSString *)name;
 
 + (void)setUserID:(nullable NSString *)userID;

analytics/src_ios/fake/FIRAnalytics.mm

@@ -60,6 +60,11 @@ + (void)initiateOnDeviceConversionMeasurementWithEmailAddress:(nonnull NSString
                           { [emailAddress UTF8String] });
 }
 
++ (void)initiateOnDeviceConversionMeasurementWithPhoneNumber:(nonnull NSString *)phoneNumber {
+  FakeReporter->AddReport("+[FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:]",
+                          { [phoneNumber UTF8String] });
+}
+
 + (void)setUserPropertyString:(nullable NSString *)value forName:(nonnull NSString *)name {
   FakeReporter->AddReport("+[FIRAnalytics setUserPropertyString:forName:]",
                           { [name UTF8String], value ? [value UTF8String] : "nil" });

analytics/tests/analytics_test.cc

@@ -232,6 +232,16 @@ TEST_F(AnalyticsTest,
   InitiateOnDeviceConversionMeasurementWithEmailAddress("my_email");
 }
 
+TEST_F(AnalyticsTest,
+       TestInitiateOnDeviceConversionMeasurementWithPhoneNumber) {
+  // InitiateOnDeviceConversionMeasurementWithPhoneNumber is no-op on Android
+  AddExpectationApple(
+      "+[FIRAnalytics initiateOnDeviceConversionMeasurementWithPhoneNumber:]",
+      {"+15551234567"});
+
+  InitiateOnDeviceConversionMeasurementWithPhoneNumber("+15551234567");
+}
+
 TEST_F(AnalyticsTest, TestSetUserProperty) {
   AddExpectationAndroid("FirebaseAnalytics.setUserProperty",
                         {"my_property", "my_value"});

release_build_files/readme.md

@@ -629,6 +629,9 @@ code.
 ## Release Notes
 ### Next Release
 -   Changes
+    - Analytics (iOS): Added InitiateOnDeviceConversionMeasurementWithPhoneNumber
+      function to facilitate the [on-device conversion
+      measurement](https://support.google.com/google-ads/answer/12119136) API.
     - Auth: Add Firebase Auth Emulator support. Set the environment variable
       USE_AUTH_EMULATOR=yes (and optionally AUTH_EMULATOR_PORT, default 9099) 
       to connect to the local Firebase Auth Emulator.