Add SetDefaultEventParameters and ClearDefaultEventParameters to Analytics

This change introduces two new C++ Analytics SDK functions:
- `SetDefaultEventParameters(const std::map<std::string, Variant>& params)`: Allows setting default parameters that will be included in all subsequent `LogEvent` calls. If a `Variant::Null()` is provided as a value for a key, that specific default parameter will be cleared/removed.
- `ClearDefaultEventParameters()`: Clears all currently set default event parameters.

Platform implementations:
- iOS: Uses `[FIRAnalytics setDefaultEventParameters:]`. `Variant::Null()` maps to `[NSNull null]` for clearing individual parameters. Calling with `nil` clears all.
- Android: Uses `FirebaseAnalytics.setDefaultEventParameters(Bundle)`. `Variant::Null()` results in `Bundle.putString(key, null)`. Calling with a `null` Bundle clears all.
- Stub: Implemented as no-ops.

Unit tests and integration tests have been updated to cover these new functionalities, including the null-value handling for clearing specific parameters and the overall clearing of all parameters.

Author: google-labs-jules[bot]

analytics/integration_test/src/integration_test.cc

@@ -341,4 +341,61 @@ TEST_F(FirebaseAnalyticsTest, TestSetConsent) {
   did_test_setconsent_ = true;
 }
 
+TEST_F(FirebaseAnalyticsTest, TestDefaultEventParametersUsage) {
+  LogInfo("Testing SetDefaultEventParameters with initial values, then updating with Null.");
+
+  std::map<std::string, firebase::analytics::Variant> initial_defaults;
+  initial_defaults["initial_key"] = "initial_value";
+  initial_defaults["key_to_be_nulled"] = "text_before_null";
+  initial_defaults["numeric_default"] = 12345LL;
+
+  LogInfo("Setting initial default event parameters.");
+  firebase::analytics::SetDefaultEventParameters(initial_defaults);
+  // Log an event that would pick up these defaults.
+  firebase::analytics::LogEvent("event_with_initial_defaults");
+  LogInfo("Logged event_with_initial_defaults.");
+  ProcessEvents(500); // Short pause for event logging, if it matters for backend.
+
+  std::map<std::string, firebase::analytics::Variant> updated_defaults;
+  updated_defaults["key_to_be_nulled"] = firebase::analytics::Variant::Null();
+  updated_defaults["another_key"] = "another_value";
+  // "initial_key" should persist if not overwritten.
+  // "numeric_default" should persist.
+
+  LogInfo("Updating default event parameters, setting key_to_be_nulled to Null.");
+  firebase::analytics::SetDefaultEventParameters(updated_defaults);
+  // Log an event that would pick up the updated defaults.
+  firebase::analytics::LogEvent("event_after_nulling_and_adding");
+  LogInfo("Logged event_after_nulling_and_adding.");
+  ProcessEvents(500);
+
+  // For this C++ SDK integration test, we primarily ensure API calls complete.
+  // Actual parameter presence on logged events would be verified by backend/native tests.
+  LogInfo("TestDefaultEventParametersUsage completed. Calls were made successfully.");
+}
+
+TEST_F(FirebaseAnalyticsTest, TestClearDefaultEventParametersFunctionality) {
+  LogInfo("Testing ClearDefaultEventParameters.");
+
+  std::map<std::string, firebase::analytics::Variant> defaults_to_clear;
+  defaults_to_clear["default_one"] = "will_be_cleared";
+  defaults_to_clear["default_two"] = 9876LL;
+
+  LogInfo("Setting default parameters before clearing.");
+  firebase::analytics::SetDefaultEventParameters(defaults_to_clear);
+  // Log an event that would pick up these defaults.
+  firebase::analytics::LogEvent("event_before_global_clear");
+  LogInfo("Logged event_before_global_clear.");
+  ProcessEvents(500);
+
+  LogInfo("Calling ClearDefaultEventParameters.");
+  firebase::analytics::ClearDefaultEventParameters();
+  // Log an event that should not have the previous defaults.
+  firebase::analytics::LogEvent("event_after_global_clear");
+  LogInfo("Logged event_after_global_clear.");
+  ProcessEvents(500);
+
+  LogInfo("TestClearDefaultEventParametersFunctionality completed. Call was made successfully.");
+}
+
 }  // namespace firebase_testapp_automated

analytics/src/analytics_android.cc

@@ -58,6 +58,8 @@ static const ::firebase::App* g_app = nullptr;
     "()Lcom/google/android/gms/tasks/Task;"),                                 \
   X(GetSessionId, "getSessionId",                                             \
     "()Lcom/google/android/gms/tasks/Task;"),                                 \
+  X(SetDefaultEventParameters, "setDefaultEventParameters",                   \
+    "(Landroid/os/Bundle;)V", util::kMethodTypeInstance),                     \
   X(GetInstance, "getInstance", "(Landroid/content/Context;)"                 \
     "Lcom/google/firebase/analytics/FirebaseAnalytics;",                      \
     firebase::util::kMethodTypeStatic)
@@ -609,6 +611,72 @@ void ResetAnalyticsData() {
   util::CheckAndClearJniExceptions(env);
 }
 
+void SetDefaultEventParameters(
+    const std::map<std::string, Variant>& default_parameters) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  JNIEnv* env = g_app->GetJNIEnv();
+  if (!env) return;
+
+  jobject bundle =
+      env->NewObject(util::bundle::GetClass(),
+                     util::bundle::GetMethodId(util::bundle::kConstructor));
+  if (util::CheckAndClearJniExceptions(env) || !bundle) {
+    LogError("Failed to create Bundle for SetDefaultEventParameters.");
+    if (bundle) env->DeleteLocalRef(bundle);
+    return;
+  }
+
+  for (const auto& pair : default_parameters) {
+    jstring key_jstring = env->NewStringUTF(pair.first.c_str());
+    if (util::CheckAndClearJniExceptions(env) || !key_jstring) {
+      LogError("Failed to create jstring for key: %s", pair.first.c_str());
+      if (key_jstring) env->DeleteLocalRef(key_jstring);
+      continue;
+    }
+
+    if (pair.second.is_null()) {
+      // Equivalent to Bundle.putString(String key, String value) with value as null.
+      env->CallVoidMethod(bundle, util::bundle::GetMethodId(util::bundle::kPutString),
+                          key_jstring, nullptr);
+      if (util::CheckAndClearJniExceptions(env)) {
+          LogError("Failed to put null string for key: %s", pair.first.c_str());
+      }
+    } else {
+      if (!AddVariantToBundle(env, bundle, pair.first.c_str(), pair.second)) {
+        // AddVariantToBundle already logs errors for unsupported types.
+      }
+    }
+    env->DeleteLocalRef(key_jstring);
+  }
+
+  env->CallVoidMethod(g_analytics_class_instance,
+                      analytics::GetMethodId(analytics::kSetDefaultEventParameters),
+                      bundle);
+  if (util::CheckAndClearJniExceptions(env)) {
+    LogError("Failed to call setDefaultEventParameters on Java instance.");
+  }
+
+  env->DeleteLocalRef(bundle);
+}
+
+void ClearDefaultEventParameters() {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  JNIEnv* env = g_app->GetJNIEnv();
+  if (!env) return;
+
+  // Calling with nullptr bundle should clear the parameters.
+  env->CallVoidMethod(g_analytics_class_instance,
+                      analytics::GetMethodId(analytics::kSetDefaultEventParameters),
+                      nullptr);
+  if (util::CheckAndClearJniExceptions(env)) {
+    // This might happen if the method isn't available on older SDKs,
+    // or if some other JNI error occurs.
+    LogError("Failed to call setDefaultEventParameters(null) on Java instance. "
+             "This may indicate the method is not available on this Android SDK version "
+             "or another JNI error occurred.");
+  }
+}
+
 Future<std::string> GetAnalyticsInstanceId() {
   FIREBASE_ASSERT_RETURN(GetAnalyticsInstanceIdLastResult(),
                          internal::IsInitialized());

analytics/src/analytics_ios.mm

@@ -373,6 +373,42 @@ void SetSessionTimeoutDuration(int64_t milliseconds) {
       setSessionTimeoutInterval:static_cast<NSTimeInterval>(milliseconds) / kMillisecondsPerSecond];
 }
 
+void SetDefaultEventParameters(
+    const std::map<std::string, Variant>& default_parameters) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  NSMutableDictionary* ns_default_parameters =
+      [[NSMutableDictionary alloc] initWithCapacity:default_parameters.size()];
+  for (const auto& pair : default_parameters) {
+    NSString* key = SafeString(pair.first.c_str());
+    const Variant& value = pair.second;
+
+    if (value.is_null()) {
+      [ns_default_parameters setObject:[NSNull null] forKey:key];
+    } else if (value.is_int64()) {
+      [ns_default_parameters setObject:[NSNumber numberWithLongLong:value.int64_value()] forKey:key];
+    } else if (value.is_double()) {
+      [ns_default_parameters setObject:[NSNumber numberWithDouble:value.double_value()] forKey:key];
+    } else if (value.is_string()) {
+      [ns_default_parameters setObject:SafeString(value.string_value()) forKey:key];
+    } else if (value.is_bool()) {
+      [ns_default_parameters setObject:[NSNumber numberWithBool:value.bool_value()] forKey:key];
+    } else {
+      // Log an error for unsupported types.
+      // Note: FIRAnalytics.setDefaultEventParameters only supports NSNumber, NSString, NSNull.
+      // It does not support nested collections (NSArray, NSDictionary) unlike LogEvent.
+      LogError("SetDefaultEventParameters: Unsupported Variant type (%s) for key %s. "
+               "Only Int64, Double, String, Bool, and Null are supported for default event parameters.",
+               Variant::TypeName(value.type()), pair.first.c_str());
+    }
+  }
+  [FIRAnalytics setDefaultEventParameters:ns_default_parameters];
+}
+
+void ClearDefaultEventParameters() {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  [FIRAnalytics setDefaultEventParameters:nil];
+}
+
 void ResetAnalyticsData() {
   MutexLock lock(g_mutex);
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());

analytics/src/analytics_stub.cc

@@ -142,6 +142,17 @@ void SetSessionTimeoutDuration(int64_t /*milliseconds*/) {
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
 }
 
+void SetDefaultEventParameters(
+    const std::map<std::string, Variant>& /*default_parameters*/) {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  // This is a stub implementation. No operation needed.
+}
+
+void ClearDefaultEventParameters() {
+  FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
+  // This is a stub implementation. No operation needed.
+}
+
 void ResetAnalyticsData() {
   FIREBASE_ASSERT_RETURN_VOID(internal::IsInitialized());
   g_fake_instance_id++;

analytics/src/include/firebase/analytics.h

@@ -558,6 +558,23 @@ void SetSessionTimeoutDuration(int64_t milliseconds);
 /// instance id.
 void ResetAnalyticsData();
 
+/// @brief Sets the default event parameters.
+///
+/// These parameters will be automatically logged with all calls to `LogEvent`.
+/// Default parameters are overridden by parameters supplied to the `LogEvent`
+/// method.
+///
+/// When a value in the `default_parameters` map is
+/// `firebase::Variant::Null()`, it signifies that the default parameter for
+/// that specific key should be cleared.
+///
+/// @param[in] default_parameters A map of parameter names to Variant values.
+void SetDefaultEventParameters(
+    const std::map<std::string, Variant>& default_parameters);
+
+/// @brief Clears all default event parameters.
+void ClearDefaultEventParameters();
+
 /// Get the instance ID from the analytics service.
 ///
 /// @note This is *not* the same ID as the ID returned by

analytics/src_ios/fake/FIRAnalytics.h

@@ -37,4 +37,6 @@
 
 + (void)resetAnalyticsData;
 
++ (void)setDefaultEventParameters:(nullable NSDictionary<NSString *, id> *)parameters;
+
 @end

analytics/src_ios/fake/FIRAnalytics.mm

@@ -21,6 +21,9 @@
 @implementation FIRAnalytics
 
 + (NSString *)stringForValue:(id)value {
+  if (value == [NSNull null]) {
+    return @"<NSNull>";
+  }
   return [NSString stringWithFormat:@"%@", value];
 }
 
@@ -94,4 +97,14 @@ + (void)resetAnalyticsData {
   FakeReporter->AddReport("+[FIRAnalytics resetAnalyticsData]", {});
 }
 
++ (void)setDefaultEventParameters:(nullable NSDictionary<NSString *, id> *)parameters {
+  if (parameters == nil) {
+    FakeReporter->AddReport("+[FIRAnalytics setDefaultEventParameters:]", {"nil"});
+  } else {
+    NSString *parameterString = [self stringForParameters:parameters];
+    FakeReporter->AddReport("+[FIRAnalytics setDefaultEventParameters:]",
+                            { [parameterString UTF8String] });
+  }
+}
+
 @end

analytics/src_java/fake/com/google/firebase/analytics/FirebaseAnalytics.java

@@ -79,4 +79,30 @@ public void setSessionTimeoutDuration(long milliseconds) {
     FakeReporter.addReport(
         "FirebaseAnalytics.setSessionTimeoutDuration", Long.toString(milliseconds));
   }
+
+  public void setDefaultEventParameters(Bundle bundle) {
+    if (bundle == null) {
+        FakeReporter.addReport("FirebaseAnalytics.setDefaultEventParameters", "null");
+    } else {
+        StringBuilder paramsString = new StringBuilder();
+        // Sort keys for predictable ordering.
+        for (String key : new TreeSet<>(bundle.keySet())) {
+            paramsString.append(key);
+            paramsString.append("=");
+            Object value = bundle.get(key); // Get as Object first
+            if (value == null) {
+                // This case handles when bundle.putString(key, null) was called.
+                paramsString.append("<null_string_value>");
+            } else {
+                paramsString.append(value.toString());
+            }
+            paramsString.append(",");
+        }
+        // Remove trailing comma if paramsString is not empty
+        if (paramsString.length() > 0) {
+            paramsString.setLength(paramsString.length() - 1);
+        }
+        FakeReporter.addReport("FirebaseAnalytics.setDefaultEventParameters", paramsString.toString());
+    }
+  }
 }

analytics/tests/analytics_test.cc

@@ -296,5 +296,89 @@ TEST_F(AnalyticsTest, TestGetAnalyticsInstanceId) {
   EXPECT_EQ(std::string("FakeAnalyticsInstanceId0"), *result.result());
 }
 
+TEST_F(AnalyticsTest, TestSetDefaultEventParameters) {
+  // Android part is not tested here as it's about iOS fakes.
+  // This test focuses on the iOS fake reporting.
+  // Android: AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {"my_param_bool=true,my_param_double=3.14,my_param_int=123,my_param_string=hello"});
+  AddExpectationApple("+[FIRAnalytics setDefaultEventParameters:]",
+                      {"my_param_bool=1,my_param_double=3.14,my_param_int=123,my_param_string=hello"});
+
+  std::map<std::string, Variant> default_params;
+  default_params["my_param_string"] = "hello";
+  default_params["my_param_double"] = 3.14;
+  default_params["my_param_int"] = 123;
+  default_params["my_param_bool"] = true; // Note: [NSNumber numberWithBool:YES] stringifies to 1
+
+  SetDefaultEventParameters(default_params);
+}
+
+TEST_F(AnalyticsTest, TestSetDefaultEventParametersWithNull) {
+  // Android: AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {"key_to_clear=null,other_key=value"});
+  AddExpectationApple("+[FIRAnalytics setDefaultEventParameters:]",
+                      {"key_to_clear=<NSNull>,other_key=value"});
+
+  std::map<std::string, Variant> default_params;
+  default_params["key_to_clear"] = Variant::Null();
+  default_params["other_key"] = "value";
+
+  SetDefaultEventParameters(default_params);
+}
+
+TEST_F(AnalyticsTest, TestSetDefaultEventParametersEmpty) {
+  // Android: AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {""}); // Or however an empty bundle is represented
+  AddExpectationApple("+[FIRAnalytics setDefaultEventParameters:]", {""});
+
+  std::map<std::string, Variant> default_params;
+  SetDefaultEventParameters(default_params);
+}
+
+TEST_F(AnalyticsTest, TestClearDefaultEventParameters) {
+  // Android: AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {"null"}); // Passing null bundle
+  AddExpectationApple("+[FIRAnalytics setDefaultEventParameters:]", {"nil"});
+
+  ClearDefaultEventParameters();
+}
+
+TEST_F(AnalyticsTest, TestSetDefaultEventParametersAndroid) {
+  AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters",
+                        {"my_bool=true,my_double=3.14,my_int=123,my_string=hello"});
+
+  std::map<std::string, Variant> default_params;
+  default_params["my_string"] = "hello";
+  default_params["my_double"] = 3.14;
+  default_params["my_int"] = 123;
+  default_params["my_bool"] = true;
+
+  SetDefaultEventParameters(default_params);
+  WaitForMainThreadTask();
+}
+
+TEST_F(AnalyticsTest, TestSetDefaultEventParametersWithNullValueAndroid) {
+  AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters",
+                        {"key_to_clear=<null_string_value>,other_key=value"});
+
+  std::map<std::string, Variant> default_params;
+  default_params["key_to_clear"] = Variant::Null();
+  default_params["other_key"] = "value";
+
+  SetDefaultEventParameters(default_params);
+  WaitForMainThreadTask();
+}
+
+TEST_F(AnalyticsTest, TestSetDefaultEventParametersEmptyAndroid) {
+  AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {""});
+
+  std::map<std::string, Variant> default_params;
+  SetDefaultEventParameters(default_params);
+  WaitForMainThreadTask();
+}
+
+TEST_F(AnalyticsTest, TestClearDefaultEventParametersAndroid) {
+  AddExpectationAndroid("FirebaseAnalytics.setDefaultEventParameters", {"null"});
+
+  ClearDefaultEventParameters();
+  WaitForMainThreadTask();
+}
+
 }  // namespace analytics
 }  // namespace firebase