[firebase_analytics] add missing named events tracking (flutter#1850)

packages/firebase_analytics/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 4.0.0
+
+* Added new tracking events:
+  - `logLevelStart`
+  - `logLevelEnd`
+  - `logRemoveFromCart`
+  - `logSetCheckoutOption`
+* **Breaking change**. Add new required parameter `method` to `logShare` event tracking.
+* **Breaking change**. The following event names are reserved and cannot be used:
+  - `ad_activeview`
+  - `ad_click`
+  - `ad_exposure`
+  - `ad_impression`
+  - `ad_query`
+  - `adunit_exposure`
+  - `first_visit`
+  - `screen_view`
+
 ## 3.0.3
 
 * Automatically use version from pubspec.yaml when reporting usage to Firebase.

packages/firebase_analytics/example/lib/main.dart

@@ -227,9 +227,9 @@ class _MyHomePageState extends State<MyHomePage> {
       itemId: 'test item id',
     );
     await analytics.logShare(
-      contentType: 'test content type',
-      itemId: 'test item id',
-    );
+        contentType: 'test content type',
+        itemId: 'test item id',
+        method: 'facebook');
     await analytics.logSignUp(
       signUpMethod: 'test sign up method',
     );

packages/firebase_analytics/lib/firebase_analytics.dart

@@ -446,6 +446,36 @@ class FirebaseAnalytics {
     );
   }
 
+  /// Logs the standard `level_start` event.
+  ///
+  /// See: https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event.html#LEVEL_START
+  Future<void> logLevelStart({
+    @required String levelName,
+  }) {
+    return logEvent(
+      name: 'level_start',
+      parameters: filterOutNulls(<String, dynamic>{
+        _LEVEL_NAME: levelName,
+      }),
+    );
+  }
+
+  /// Logs the standard `level_end` event.
+  ///
+  /// See: https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event.html#LEVEL_END
+  Future<void> logLevelEnd({
+    @required String levelName,
+    int success,
+  }) {
+    return logEvent(
+      name: 'level_end',
+      parameters: filterOutNulls(<String, dynamic>{
+        _LEVEL_NAME: levelName,
+        _SUCCESS: success,
+      }),
+    );
+  }
+
   /// Logs the standard `login` event.
   ///
   /// Apps with a login feature can report this event to signify that a user
@@ -544,6 +574,43 @@ class FirebaseAnalytics {
     );
   }
 
+  /// Logs the standard `remove_from_cart` event.
+  /// See: https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event.html#REMOVE_FROM_CART
+  Future<void> logRemoveFromCart({
+    @required String itemId,
+    @required String itemName,
+    @required String itemCategory,
+    @required int quantity,
+    double price,
+    double value,
+    String currency,
+    String origin,
+    String itemLocationId,
+    String destination,
+    String startDate,
+    String endDate,
+  }) {
+    _requireValueAndCurrencyTogether(value, currency);
+
+    return logEvent(
+      name: 'remove_from_cart',
+      parameters: filterOutNulls(<String, dynamic>{
+        _QUANTITY: quantity,
+        _ITEM_CATEGORY: itemCategory,
+        _ITEM_NAME: itemName,
+        _ITEM_ID: itemId,
+        _VALUE: value,
+        _PRICE: price,
+        _CURRENCY: currency,
+        _ITEM_LOCATION_ID: itemLocationId,
+        _ORIGIN: origin,
+        _START_DATE: startDate,
+        _END_DATE: endDate,
+        _DESTINATION: destination,
+      }),
+    );
+  }
+
   /// Logs the standard `search` event.
   ///
   /// Apps that support search features can use this event to contextualize
@@ -599,6 +666,21 @@ class FirebaseAnalytics {
     );
   }
 
+  /// Logs the standard `set_checkout_option` event.
+  /// See: https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event.html#SET_CHECKOUT_OPTION
+  Future<void> logSetCheckoutOption({
+    @required int checkoutStep,
+    @required String checkoutOption,
+  }) {
+    return logEvent(
+      name: 'set_checkout_option',
+      parameters: filterOutNulls(<String, dynamic>{
+        _CHECKOUT_STEP: checkoutStep,
+        _CHECKOUT_OPTION: checkoutOption,
+      }),
+    );
+  }
+
   /// Logs the standard `share` event.
   ///
   /// Apps with social features can log the Share event to identify the most
@@ -608,12 +690,14 @@ class FirebaseAnalytics {
   Future<void> logShare({
     @required String contentType,
     @required String itemId,
+    @required String method,
   }) {
     return logEvent(
       name: 'share',
       parameters: filterOutNulls(<String, dynamic>{
         _CONTENT_TYPE: contentType,
         _ITEM_ID: itemId,
+        _METHOD: method,
       }),
     );
   }
@@ -861,17 +945,25 @@ void _requireValueAndCurrencyTogether(double value, String currency) {
 ///
 /// See: https://firebase.google.com/docs/reference/android/com/google/firebase/analytics/FirebaseAnalytics.Event.html
 const List<String> _reservedEventNames = <String>[
+  'ad_activeview',
+  'ad_click',
+  'ad_exposure',
+  'ad_impression',
+  'ad_query',
+  'adunit_exposure',
   'app_clear_data',
   'app_uninstall',
   'app_update',
   'error',
   'first_open',
+  'first_visit',
   'in_app_purchase',
   'notification_dismiss',
   'notification_foreground',
   'notification_open',
   'notification_receive',
   'os_update',
+  'screen_view',
   'session_start',
   'user_engagement',
 ];
@@ -915,6 +1007,11 @@ const String _DESTINATION = 'destination';
 /// The arrival date, check-out date, or rental end date for the item.
 const String _END_DATE = 'end_date';
 
+/// Indicates that the associated event should either
+/// extend the current session or start a new session
+/// if no session was active when the event was logged.
+// const String _EXTENDED_SESSION = 'extend_session';
+
 /// Flight number for travel events.
 const String _FLIGHT_NUMBER = 'flight_number';
 
@@ -930,12 +1027,45 @@ const String _ITEM_ID = 'item_id';
 /// The Google Place ID that corresponds to the associated item.
 const String _ITEM_LOCATION_ID = 'item_location_id';
 
-/// Item name.
+/// Item Brand.
+// const String _ITEM_BRAND = 'item_brand';
+
+/// Item Variant.
+// const String _ITEM_VARIANT = 'item_variant';
+
+/// The list in which the item was presented to the user.
+// const String _ITEM_LIST = 'item_list';
+
+/// The checkout step (1..N).
+const String _CHECKOUT_STEP = 'checkout_step';
+
+/// Some option on a step in an ecommerce flow.
+const String _CHECKOUT_OPTION = 'checkout_option';
+
+/// The name of a creative used in a promotional spot.
+// const String _CREATIVE_NAME = 'creative_name';
+
+/// The name of a creative slot.
+// const String _CREATIVE_SLOT = 'creative_slot';
+
+/// The store or affiliation from which this transaction occurred.
+// const String _AFFILIATION = 'affiliation';
+
+/// The index of an item in a list.
+// const String _INDEX = 'index';
+
+/// Item name (String).
 const String _ITEM_NAME = 'item_name';
 
 /// Level in game (long).
 const String _LEVEL = 'level';
 
+/// The name of a level in a game (String).
+const String _LEVEL_NAME = 'level_name';
+
+/// The result of an operation (long).
+const String _SUCCESS = 'success';
+
 /// Location.
 const String _LOCATION = 'location';
 

packages/firebase_analytics/pubspec.yaml

@@ -3,7 +3,7 @@ description: Flutter plugin for Google Analytics for Firebase, an app measuremen
   solution that provides insight on app usage and user engagement on Android and iOS.
 author: Flutter Team <flutter-dev@googlegroups.com>
 homepage: https://github.com/flutter/plugins/tree/master/packages/firebase_analytics
-version: 3.0.3
+version: 4.0.0
 
 flutter:
   plugin:

packages/firebase_analytics/test/firebase_analytics_test.dart

@@ -220,6 +220,19 @@ void main() {
               level: 56,
             ));
 
+    smokeTest(
+        'level_start',
+        () => analytics.logLevelStart(
+              levelName: 'level-name',
+            ));
+
+    smokeTest(
+        'level_end',
+        () => analytics.logLevelEnd(
+              levelName: 'level-name',
+              success: 1,
+            ));
+
     smokeTest('login', () => analytics.logLogin());
 
     smokeTest(
@@ -263,6 +276,7 @@ void main() {
         () => analytics.logShare(
               contentType: 'test content type',
               itemId: 'test item id',
+              method: 'test method',
             ));
 
     smokeTest(
@@ -309,6 +323,11 @@ void main() {
               searchTerm: 'test search term',
             ));
 
+    smokeTest('set_checkout_option', () {
+      return analytics.logSetCheckoutOption(
+          checkoutStep: 1, checkoutOption: 'some credit card');
+    });
+
     void testRequiresValueAndCurrencyTogether(
         String methodName, Future<void> testFn()) {
       test('$methodName requires value and currency together', () async {
@@ -331,6 +350,16 @@ void main() {
       );
     });
 
+    testRequiresValueAndCurrencyTogether('logRemoveFromCart', () {
+      return analytics.logRemoveFromCart(
+        itemId: 'test-id',
+        itemName: 'test-name',
+        itemCategory: 'test-category',
+        quantity: 5,
+        value: 123.90,
+      );
+    });
+
     testRequiresValueAndCurrencyTogether('logAddToWishlist', () {
       return analytics.logAddToWishlist(
         itemId: 'test-id',