diff --git a/analytics/src/FirebaseAnalytics.cs b/analytics/src/FirebaseAnalytics.cs index 87a1842a5..200b35131 100644 --- a/analytics/src/FirebaseAnalytics.cs +++ b/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)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 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)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 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() { diff --git a/analytics/src/swig/analytics.i b/analytics/src/swig/analytics.i index 866f6d4fb..00df5b92a 100644 --- a/analytics/src/swig/analytics.i +++ b/analytics/src/swig/analytics.i @@ -63,7 +63,7 @@ void LogEvent(const char* name, std::vector 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 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 parameter_names, + std::vector 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 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& settings) { std::map converted; @@ -95,9 +115,12 @@ void SetConsentWithInts(const std::map& 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 parameter_names, std::vector parameter_values); +void SetDefaultEventParameters(std::vector parameter_names, + std::vector parameter_values); void SetConsentWithInts(const std::map& settings); } // namespace analytics } // namespace firebase diff --git a/docs/readme.md b/docs/readme.md index c16676dc2..fcf67dfe5 100644 --- a/docs/readme.md +++ b/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.