Add InitiateOnDeviceConversion method to Analytics (#961)

* Add InitiateOnDeviceConversion to c++ sdk

* Added release notes

Author: AlmostMatt

analytics/integration_test/src/integration_test.cc

@@ -108,6 +108,9 @@ TEST_F(FirebaseAnalyticsTest, TestSetProperties) {
       firebase::analytics::kUserPropertySignUpMethod, "Google");
   // Set the user ID.
   firebase::analytics::SetUserId("my_integration_test_user");
+  // Initiate on-device conversion measurement.
+  firebase::analytics::InitiateOnDeviceConversionMeasurementWithEmailAddress(
+      "my_email@site.com");
 }
 
 TEST_F(FirebaseAnalyticsTest, TestLogEvents) {

analytics/src/analytics_android.cc

@@ -264,6 +264,16 @@ void LogEvent(const char* name, const Parameter* parameters,
   });
 }
 
+/// Initiates on-device conversion measurement given a user email address on iOS
+/// (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+void InitiateOnDeviceConversionMeasurementWithEmailAddress(
+    const char* email_address) {
+  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

@@ -16,6 +16,7 @@
 
 #import <Foundation/Foundation.h>
 
+#import "FIRAnalytics+OnDevice.h"
 #import "FIRAnalytics.h"
 
 #include "analytics/src/include/firebase/analytics.h"
@@ -222,6 +223,14 @@ void LogEvent(const char* name, const Parameter* parameters, size_t number_of_pa
   [FIRAnalytics logEventWithName:@(name) parameters:parameters_dict];
 }
 
+/// Initiates on-device conversion measurement given a user email address on iOS (no-op on
+/// Android). On iOS, requires dependency GoogleAppMeasurementOnDeviceConversion to be linked
+/// in, otherwise it is a no-op.
+void InitiateOnDeviceConversionMeasurementWithEmailAddress(const char* email_address) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  [FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:@(email_address)];
+}
+
 // 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

@@ -92,6 +92,15 @@ void LogEvent(const char* /*name*/, const Parameter* /*parameters*/,
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
 }
 
+/// Initiates on-device conversion measurement given a user email address on iOS
+/// (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+void InitiateOnDeviceConversionMeasurementWithEmailAddress(
+    const char* email_address) {
+  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

@@ -433,6 +433,7 @@ void LogEvent(const char* name);
 // in the C# code.
 %csmethodmodifiers LogEvent "public unsafe"
 #endif  // SWIG
+// clang-format on
 
 /// @brief Log an event with associated parameters.
 ///
@@ -456,7 +457,15 @@ void LogEvent(const char* name);
 /// array.
 void LogEvent(const char* name, const Parameter* parameters,
               size_t number_of_parameters);
-// clang-format on
+
+/// Initiates on-device conversion measurement given a user email address on iOS
+/// (no-op on Android). On iOS, requires dependency
+/// GoogleAppMeasurementOnDeviceConversion to be linked in, otherwise it is a
+/// no-op.
+/// @param[in] email_address User email address. Include a domain name for all
+/// email addresses (e.g. gmail.com or hotmail.co.jp).
+void InitiateOnDeviceConversionMeasurementWithEmailAddress(
+    const char* email_address);
 
 /// @brief Set a user property to the given value.
 ///

analytics/src_ios/fake/FIRAnalytics.h

@@ -21,6 +21,8 @@
 + (void)logEventWithName:(nonnull NSString *)name
               parameters:(nullable NSDictionary<NSString *, id> *)parameters;
 
++ (void)initiateOnDeviceConversionMeasurementWithEmailAddress:(nonnull NSString *)emailAddress;
+
 + (void)setUserPropertyString:(nullable NSString *)value forName:(nonnull NSString *)name;
 
 + (void)setUserID:(nullable NSString *)userID;

analytics/src_ios/fake/FIRAnalytics.mm

@@ -55,6 +55,11 @@ + (void)logEventWithName:(nonnull NSString *)name
   }
 }
 
++ (void)initiateOnDeviceConversionMeasurementWithEmailAddress:(nonnull NSString *)emailAddress {
+  FakeReporter->AddReport("+[FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:]",
+                          { [emailAddress 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

@@ -222,6 +222,16 @@ TEST_F(AnalyticsTest, TestLogEventParameters) {
   LogEvent("my_event", parameters, sizeof(parameters) / sizeof(parameters[0]));
 }
 
+TEST_F(AnalyticsTest,
+       TestInitiateOnDeviceConversionMeasurementWithEmailAddress) {
+  // InitiateOnDeviceConversionMeasurementWithEmailAddress is no-op on Android
+  AddExpectationApple(
+      "+[FIRAnalytics initiateOnDeviceConversionMeasurementWithEmailAddress:]",
+      {"my_email"});
+
+  InitiateOnDeviceConversionMeasurementWithEmailAddress("my_email");
+}
+
 TEST_F(AnalyticsTest, TestSetUserProperty) {
   AddExpectationAndroid("FirebaseAnalytics.setUserProperty",
                         {"my_property", "my_value"});

release_build_files/readme.md

@@ -605,6 +605,8 @@ code.
       only using AdMob, Analytics, Remote Config, or Messaging.
     - Functions: Add a new method `GetHttpsCallableFromURL`, to create callables
       with URLs other than cloudfunctions.net.
+    - Analytics (iOS): Added InitiateOnDeviceConversionMeasurementWithEmail function to facilitate the
+      [on-device conversion measurement](https://support.google.com/google-ads/answer/12119136) API.
 
 ### 9.0.0
 -   Changes