Feat: add SetDefaultEventParameters and have EventLog to take in a IEnumerable (#1359)

* feat(analytics): Add SetDefaultEventParameters and overload LogEvent

Adds the `SetDefaultEventParameters` function to the Firebase Analytics SDK. This allows users to set default parameters for all events.

Also adds an overload to the `LogEvent` function to accept an `IEnumerable<Parameter>` in addition to `params Parameter[]`.

* feat(analytics): Add release notes for SetDefaultEventParameters

* fixup: Formatting and wording changes

* fixup: reword readme changes to be consistent with csharp changes

Author: AustinBenoit

analytics/src/FirebaseAnalytics.cs

@@ -15,6 +15,7 @@
  */
 
 using System.Threading.Tasks;
+using System.Collections.Generic;
 
 namespace Firebase.Analytics {
 
@@ -206,18 +207,79 @@ public static void LogEvent(string name) {
   ///
   /// @param[in] parameters A parameter array of `Parameter` instances.
   public static void LogEvent(string name, params Parameter[] parameters) {
-    // Convert the Parameter array into a StringList and VariantList to pass to C++
+    LogEvent(name, (IEnumerable<Parameter>)parameters);
+  }
+
+  /// @brief Log an event with associated parameters.
+  ///
+  /// An Event is an important occurrence in your app that you want to measure.
+  /// You can report up to 500 different types of events per app and you can
+  /// associate up to 25 unique parameters with each Event type.
+  ///
+  /// Some common events are in the reference guide via the
+  /// FirebaseAnalytics.Event* constants, but you may also choose to specify
+  /// custom event types that are associated with your specific app.
+  ///
+  /// @param[in] name Name of the event to log. Should contain 1 to 40
+  /// alphanumeric characters or underscores. The name must start with an
+  /// alphabetic character. Some event names are reserved.
+  /// See the FirebaseAnalytics.Event properties for the list of reserved event
+  /// names.
+  /// The "firebase_" prefix is reserved and should not be used. Note that event
+  /// names are case-sensitive and that logging two events whose names differ
+  /// only in case will result in two distinct events.
+  ///
+  /// @param[in] parameters An enumerable list of `Parameter` instances.
+  public static void LogEvent(string name, IEnumerable<Parameter> parameters) {
     StringList parameterNames = new StringList();
     VariantList parameterValues = new VariantList();
-
-    foreach (Parameter p in parameters) {
-      parameterNames.Add(p.Name);
-      parameterValues.Add(Firebase.Variant.FromObject(p.Value));
+    if (parameters != null) {
+      foreach (Parameter p in parameters) {
+        parameterNames.Add(p.Name);
+        parameterValues.Add(Firebase.Variant.FromObject(p.Value));
+      }
     }
-
     FirebaseAnalyticsInternal.LogEvent(name, parameterNames, parameterValues);
   }
 
+  /// @brief Adds parameters that will be set on every event logged from the SDK.
+  ///
+  /// Adds parameters that will be set on every event logged from the SDK,
+  /// including automatic ones. The values passed in the parameters bundle will
+  /// be added to the map of default event parameters. These parameters persist
+  /// across app runs. They are of lower precedence than event parameters, so if
+  /// an event parameter and a parameter set using this API have the same name,
+  /// the value of the event parameter will be used. The same limitations on
+  /// event parameters apply to default event parameters.
+  ///
+  /// @param[in] parameters A parameter array of `Parameter` instances.
+  public static void SetDefaultEventParameters(params Parameter[] parameters){
+    SetDefaultEventParameters((IEnumerable<Parameter>)parameters);
+  }
+
+  /// @brief Adds parameters that will be set on every event logged from the SDK.
+  ///
+  /// Adds parameters that will be set on every event logged from the SDK,
+  /// including automatic ones. The values passed in the parameters bundle will
+  /// be added to the map of default event parameters. These parameters persist
+  /// across app runs. They are of lower precedence than event parameters, so if
+  /// an event parameter and a parameter set using this API have the same name,
+  /// the value of the event parameter will be used. The same limitations on
+  /// event parameters apply to default event parameters.
+  ///
+  /// @param[in] parameters An enumerable list of `Parameter` instances.
+  public static void SetDefaultEventParameters(IEnumerable<Parameter> parameters){
+    StringList parameterNames = new StringList();
+    VariantList parameterValues = new VariantList();
+    if (parameters != null) {
+      foreach (Parameter p in parameters) {
+        parameterNames.Add(p.Name);
+        parameterValues.Add(Firebase.Variant.FromObject(p.Value));
+      }
+    }
+    FirebaseAnalyticsInternal.SetDefaultEventParameters(parameterNames, parameterValues);
+  }
+
   /// Clears all analytics data for this app from the device and resets the app
   /// instance id.
   public static void ResetAnalyticsData() {

analytics/src/swig/analytics.i

@@ -63,7 +63,7 @@ void LogEvent(const char* name, std::vector<std::string> parameter_names,
   if (parameter_names.size() != parameter_values.size()) {
     firebase::LogError("LogEvent for %s given different list sizes (%d, %d)",
                        name, parameter_names.size(), parameter_values.size());
-    return; 
+    return;
   }
 
   size_t number_of_parameters = parameter_names.size();
@@ -78,6 +78,26 @@ void LogEvent(const char* name, std::vector<std::string> parameter_names,
   delete[] parameters;
 }
 
+// Internal version of SetDefaultEventParameters that takes in two vectors
+// of known types and converts them into C++ parameters to pass them along to
+// the public SetDefaultEventParameters
+void SetDefaultEventParameters(std::vector<std::string> parameter_names,
+              std::vector<firebase::Variant> parameter_values) {
+  if (parameter_names.size() != parameter_values.size()) {
+    firebase::LogError(
+        "SetDefaultEventParameters given different list sizes (%d, %d)",
+        parameter_names.size(), parameter_values.size());
+    return;
+  }
+  std::vector<Parameter> parameters;
+
+  for(size_t i = 0; i < parameter_names.size(); ++i) {
+    parameters.push_back(Parameter(parameter_names[i].c_str(), parameter_values[i]));
+  }
+
+  SetDefaultEventParameters(parameters);
+}
+
 // Converts from a generic int, int map to the C++ Consent enums
 void SetConsentWithInts(const std::map<int, int>& settings) {
   std::map<ConsentType, ConsentStatus> converted;
@@ -95,9 +115,12 @@ void SetConsentWithInts(const std::map<int, int>& settings) {
 // Initialize / Terminate implicitly called when App is created / destroyed.
 %ignore firebase::analytics::Initialize;
 %ignore firebase::analytics::Terminate;
-// Ignore the SendEvent that takes a Parameter array, as we handle it
+// Ignore the LogEvent that takes a Parameter array, as we handle it
 // with a custom version instead.
 %ignore firebase::analytics::LogEvent(const char*, const Parameter*, size_t);
+// Ignore the SetDefaultEventParameters that takes a Parameter array, as we
+// handle it with a custom version instead.
+%ignore firebase::analytics::SetDefaultEventParameters(const Parameter*, size_t);
 // Ignore SetConsent, in order to convert the types with our own function.
 %ignore firebase::analytics::SetConsent;
 // Ignore the Parameter class, as we don't want to expose that to C# at all.
@@ -120,6 +143,8 @@ namespace firebase {
 namespace analytics {
 void LogEvent(const char* name, std::vector<std::string> parameter_names,
               std::vector<firebase::Variant> parameter_values);
+void SetDefaultEventParameters(std::vector<std::string> parameter_names,
+              std::vector<firebase::Variant> parameter_values);
 void SetConsentWithInts(const std::map<int, int>& settings);
 }  // namespace analytics
 }  // namespace firebase

docs/readme.md

@@ -109,6 +109,13 @@ Support
 
 Release Notes
 -------------
+### Upcoming
+-   Changes
+    - Analytics: Added `SetDefaultEventParameters()` which allows developers to
+      specify a list  of parameters that will be set on every event logged.
+    - Analytics: Added a new `LogEvent()` that take in a IEnumerable of
+	  parameters.
+
 ### 13.5.0
 -   Changes
     - Firebase AI: Add support for receiving Live API Transcripts.