🐛 [firebase_analytics] Support items in FirebaseAnalytics.logEvent() (Flutter)

[JulioRennan]

What feature would you like to see?

Currently, the logEvent() method in the firebase_analytics plugin does not support passing a list of items, even though this is a common requirement for many GA4 e-commerce events. This limitation was introduced in the past due to misuse—developers were passing incorrectly typed lists, leading to unexpected behavior.

As a result, only the specialized methods like logAddToCart, logPurchase, etc., currently support List<AnalyticsEventItem>. There is no flexible way to log item-based events generically using logEvent().

Proposal

I propose reintroducing support for items in logEvent() as an optional, strongly typed parameter:

Future<void> logEvent({
  required String name,
  Map<String, Object>? parameters,
  List<AnalyticsEventItem>? items,
  AnalyticsCallOptions? callOptions,
})

Internally, the items list would be converted to a List<Map<String, Object>> (as already done in existing specialized methods) and sent to the native Analytics SDK.

To avoid previous issues with misuse, we could introduce a helper like:

_assertItemsForEventNameAreCorrect(name, items)

This would:

• Ensure items is only passed for valid GA4 event names (e.g., view_item, add_to_cart, purchase, etc.).
• Enforce the use of valid AnalyticsEventItem objects.

Benefits

• Cleaner analytics wrappers: Developers could use a single logEvent() method with named events and items, avoiding the need to expose individual calls like logAddToCart, logRemoveFromCart, etc.
• Parses directly into GA4 schema: The native SDKs already support items, so this would bring the Flutter API to parity.
• Backward-compatible: The items parameter would be optional and default to null, preserving current behavior.
• Developer-friendly: Encourages proper usage through type safety and internal validation.

🧩 Conclusion

Adding typed support for items in logEvent() would improve flexibility and reduce boilerplate for developers building analytics abstractions in Flutter. It brings consistency with other platforms and maintains safeguards to avoid past mistakes.

If the team agrees with this direction, I’d be happy to open a PR with the proposed changes.

Thanks for considering this!

[danielmessi13]

Same issue here!

[jotapetecnologia]

This would help me a lot with the custom events on my projects!