From 34934a13e51e4529299bc6ba357339e9a9d28d2d Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Sat, 3 Jun 2023 23:39:12 +0200 Subject: [PATCH 1/3] refacto: uniformized and enforced parameters of tracking methods --- CHANGELOG.md | 4 ++ README.md | 6 ++ lib/src/matomo.dart | 122 +++++++++++++++++-------------------- lib/src/matomo_action.dart | 7 ++- test/src/matomo_test.dart | 20 +++--- 5 files changed, 81 insertions(+), 78 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5384373..4d1e98c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,12 +2,16 @@ ## [4.0.0] +**Check the [Migration Guide](https://github.com/Floating-Dartists/matomo-tracker#v400) to learn about breaking changes in this version** + * Contributions from [Eric Prokop](https://github.com/EPNW-Eric) * feat: Added a persistent dispatch queue [#97](https://github.com/Floating-Dartists/matomo-tracker/pull/97) + * feat: Extended the newVisit capabilities [#105](https://github.com/Floating-Dartists/matomo-tracker/pull/105) * Contributions from [TesteurManiak](https://github.com/TesteurManiak) * chore: Updated `LICENSE` with major contributors [#100](https://github.com/Floating-Dartists/matomo-tracker/pull/100) * chore: Added a contribution guide [#101](https://github.com/Floating-Dartists/matomo-tracker/pull/101) * refacto: Added default values to `TrackingOrderItem` [#102](https://github.com/Floating-Dartists/matomo-tracker/pull/102) + * refacto: Uniformized the "track" methods parameters [#103]() _Special thanks to [Eric Prokop](https://github.com/EPNW-Eric) who greatly contributed to this release._ diff --git a/README.md b/README.md index c6853b4..8036482 100644 --- a/README.md +++ b/README.md @@ -233,6 +233,12 @@ MaterialApp( ); ``` * `MatomoEvent` has been renamed to `MatomoAction` +* `trackScreen` positional parameter `context` is now a named parameter +* `trackGoal` positional parameter `goalId` is now a named parameter: `id` +* `trackDimensions` positional parameter `dimensions` is now a named parameter +* `trackCartUpdate` positional parameters `trackingOrderItems`, `subTotal`, `taxAmount`, `shippingCost` and `discountAmount` are now named parameters +* `trackOrder` positional parameters `orderId` (now `id`), `trackingOrderItems`, `revenue` (also became a `double`), `subTotal`, `taxAmount`, `shippingCost` and `discountAmount` are now named parameters +* `trackOutlink` positional parameter `link` is now a named required parameter (also changed the type to `String`) ## v3.0.0 diff --git a/lib/src/matomo.dart b/lib/src/matomo.dart index 6c5d52d..befbac2 100644 --- a/lib/src/matomo.dart +++ b/lib/src/matomo.dart @@ -430,14 +430,18 @@ class MatomoTracker { /// /// - `campaign`: The campaign that lead to this page view. /// + /// {@template dimensions_track_parameter} /// For remarks on [dimensions] see [trackDimensions]. + /// {@endtemplate} /// + /// {@template new_visit_track_parameter} /// The [newVisit] parameter can be used to make this action the begin /// of a new visit. If it's left to `null` and this is the first `track...` /// call after [MatomoTracker.initialize], the `newVisit` from there will /// be used. - void trackScreen( - BuildContext context, { + /// {@endtemplate} + void trackScreen({ + required BuildContext context, String? pvId, String? path, Campaign? campaign, @@ -473,12 +477,9 @@ class MatomoTracker { /// /// - `campaign`: The campaign that lead to this page view. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. + /// {@macro new_visit_track_parameter} void trackScreenWithName({ required String actionName, String? pvId, @@ -514,16 +515,13 @@ class MatomoTracker { /// Tracks a conversion for a goal. /// - /// The [goalId] corresponds with `idgoal` and [revenue] with `revenue`. + /// The [id] corresponds with `idgoal` and [revenue] with `revenue`. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. - void trackGoal( - int goalId, { + /// {@macro new_visit_track_parameter} + void trackGoal({ + required int id, double? revenue, Map? dimensions, bool? newVisit, @@ -533,7 +531,7 @@ class MatomoTracker { validateDimension(dimensions); return _track( MatomoAction( - goalId: goalId, + goalId: id, revenue: revenue, dimensions: dimensions, newVisit: _inferNewVisit(newVisit), @@ -548,12 +546,9 @@ class MatomoTracker { /// manually, e.g. [TraceableClientMixin.pvId]. Setting [pvId] manually will /// take precedance over [attachLastPvId]. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. + /// {@macro new_visit_track_parameter} void trackEvent({ required EventInfo eventInfo, String? pvId, @@ -573,21 +568,23 @@ class MatomoTracker { /// Tracks custom visit dimensions. /// - /// The keys of the [dimensions] map correspond with the `dimension[1-999]` parameters. - /// This means that the keys MUST be named `dimension1`, `dimension2`, `...`. + /// The keys of the [dimensions] map correspond with the `dimension[1-999]` + /// parameters. This means that the keys MUST be named `dimension1`, + /// `dimension2`, `...`. /// - /// The keys of the [dimensions] map will be validated if they follow these rules, and if not, a - /// [ArgumentError] will be thrown. + /// The keys of the [dimensions] map will be validated if they follow these + /// rules, and if not, a [ArgumentError] will be thrown. /// /// Also note that counting starts at 1 and NOT at 0 as opposed to what is stated - /// in the [Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api) documentation. + /// in the [Tracking HTTP API](https://developer.matomo.org/api-reference/tracking-api) + /// documentation. /// /// The [newVisit] parameter can be used to make this action the begin /// of a new visit. If it's left to `null` and this is the first `track...` /// call after [MatomoTracker.initialize], the `newVisit` from there will /// be used. - void trackDimensions( - Map dimensions, { + void trackDimensions({ + required Map dimensions, bool? newVisit, }) { validateDimension(dimensions); @@ -601,15 +598,12 @@ class MatomoTracker { /// Tracks a search. /// - /// [searchKeyword] corresponds with `search`, [searchCategory] with `search_cat` and - /// [searchCount] with `search_count`. + /// [searchKeyword] corresponds with `search`, [searchCategory] with + /// `search_cat` and [searchCount] with `search_count`. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. + /// {@macro new_visit_track_parameter} void trackSearch({ required String searchKeyword, String? searchCategory, @@ -631,18 +625,15 @@ class MatomoTracker { /// Tracks a cart update. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. - void trackCartUpdate( + /// {@macro new_visit_track_parameter} + void trackCartUpdate({ List? trackingOrderItems, num? subTotal, num? taxAmount, num? shippingCost, - num? discountAmount, { + num? discountAmount, Map? dimensions, bool? newVisit, }) { @@ -651,6 +642,7 @@ class MatomoTracker { validateDimension(dimensions); return _track( MatomoAction( + // goalId should be set to 0 to track an ecommerce interaction goalId: 0, trackingOrderItems: trackingOrderItems, subTotal: subTotal, @@ -663,22 +655,23 @@ class MatomoTracker { ); } - /// Tracks an order. + /// Tracks an ecommerce order. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// [id] corresponds with `ec_id`, [trackingOrderItems] with `ec_items`, + /// [revenue] with `revenue`, [subTotal] with `ec_st`, [taxAmount] with + /// `ec_tx`, [shippingCost] with `ec_sh`, [discountAmount] with `ec_dt`. /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. - void trackOrder( - String? orderId, + /// {@template dimensions_track_parameter} + /// + /// {@macro new_visit_track_parameter} + void trackOrder({ + required String id, + required double revenue, List? trackingOrderItems, - num? revenue, num? subTotal, num? taxAmount, num? shippingCost, - num? discountAmount, { + num? discountAmount, Map? dimensions, bool? newVisit, }) { @@ -687,8 +680,9 @@ class MatomoTracker { validateDimension(dimensions); return _track( MatomoAction( + // goalId should be set to 0 to track an ecommerce interaction goalId: 0, - orderId: orderId, + orderId: id, trackingOrderItems: trackingOrderItems, revenue: revenue, subTotal: subTotal, @@ -703,14 +697,13 @@ class MatomoTracker { /// Tracks the click on an outgoing link. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// [link] corresponds with `link`. /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. - void trackOutlink( - String? link, { + /// {@template dimensions_track_parameter} + /// + /// {@macro new_visit_track_parameter} + void trackOutlink({ + required String link, Map? dimensions, bool? newVisit, }) { @@ -736,12 +729,9 @@ class MatomoTracker { /// manually, e.g. [TraceableClientMixin.pvId]. Setting [pvId] manually will /// take precedance over [attachLastPvId]. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// - /// The [newVisit] parameter can be used to make this action the begin - /// of a new visit. If it's left to `null` and this is the first `track...` - /// call after [MatomoTracker.initialize], the `newVisit` from there will - /// be used. + /// {@macro new_visit_track_parameter} void trackContentImpression({ required Content content, String? pvId, @@ -771,7 +761,7 @@ class MatomoTracker { /// view manually, e.g. [TraceableClientMixin.pvId]. Setting [pvId] manually /// will take precedance over [attachLastPvId]. /// - /// For remarks on [dimensions] see [trackDimensions]. + /// {@template dimensions_track_parameter} /// /// Note that this method is missing a `newVisit` parameter on purpose since /// it doesn't make sense to have an interaction without an impression first, diff --git a/lib/src/matomo_action.dart b/lib/src/matomo_action.dart index 1b39bd5..a9b1d7e 100644 --- a/lib/src/matomo_action.dart +++ b/lib/src/matomo_action.dart @@ -55,7 +55,10 @@ class MatomoAction { final int? goalId; final String? orderId; final List? trackingOrderItems; - final num? revenue; + + /// Used either as a monetary value when tracking a goal or as the total of + /// an ecommerce order. + final double? revenue; /// Excludes shipping final num? subTotal; @@ -100,7 +103,7 @@ class MatomoAction { int? goalId, String? orderId, List? trackingOrderItems, - num? revenue, + double? revenue, num? subTotal, num? taxAmount, num? shippingCost, diff --git a/test/src/matomo_test.dart b/test/src/matomo_test.dart index 70f14ac..f711bc8 100644 --- a/test/src/matomo_test.dart +++ b/test/src/matomo_test.dart @@ -142,7 +142,7 @@ void main() { final matomoTracker = await getInitializedMatomoTracker(); final queueLength = matomoTracker.queue.length; - matomoTracker.trackDimensions(matomoTrackerDimensions); + matomoTracker.trackDimensions(dimensions: matomoTrackerDimensions); expect(matomoTracker.queue.length, queueLength + 1); await matomoTracker.dispatchActions(); expect(matomoTracker.queue.length, 0); @@ -152,7 +152,7 @@ void main() { final matomoTracker = await getInitializedMatomoTracker(); final queueLength = matomoTracker.queue.length; - matomoTracker.trackDimensions(matomoTrackerDimensions); + matomoTracker.trackDimensions(dimensions: matomoTrackerDimensions); expect(matomoTracker.queue.length, queueLength + 1); matomoTracker.dropActions(); expect(matomoTracker.queue.length, 0); @@ -164,7 +164,7 @@ void main() { (tracker) { when(() => mockBuildContext.widget).thenReturn(matomoTrackerMockWidget); - tracker.trackScreen(mockBuildContext); + tracker.trackScreen(context: mockBuildContext); }, ); @@ -201,7 +201,7 @@ void main() { testTracking('it should be able to trackGoal', (tracker) async { tracker.trackGoal( - matomoTrackerGoalId, + id: matomoTrackerGoalId, ); }); @@ -235,7 +235,7 @@ void main() { testTracking('it should be able to trackDimensions', (tracker) async { tracker.trackDimensions( - matomoTrackerDimensions, + dimensions: matomoTrackerDimensions, ); }); @@ -246,23 +246,23 @@ void main() { }); testTracking('it should be able to trackCartUpdate', (tracker) async { - tracker.trackCartUpdate([], null, null, null, null); + tracker.trackCartUpdate(); }); testTracking('it should be able to trackOrder', (tracker) async { - tracker.trackOrder(null, [], null, null, null, null, null); + tracker.trackOrder(id: '', revenue: 0); }); testTracking('it should be able to trackOutlink', (tracker) async { - tracker.trackOutlink(null); + tracker.trackOutlink(link: ''); }); test('it should be able to handle new_visit', () async { final matomoTracker = await getInitializedMatomoTracker(); - matomoTracker.trackDimensions(matomoTrackerDimensions); + matomoTracker.trackDimensions(dimensions: matomoTrackerDimensions); expect(matomoTracker.queue.first['new_visit'], '1'); - matomoTracker.trackDimensions(matomoTrackerDimensions); + matomoTracker.trackDimensions(dimensions: matomoTrackerDimensions); expect(matomoTracker.queue.last.containsKey('new_visit'), false); }); }); From 1165996be9a5dda02c939334a98910bd8968d4bd Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Sat, 3 Jun 2023 23:41:25 +0200 Subject: [PATCH 2/3] chore: fixed CHANGELOG --- CHANGELOG.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d1e98c..7f070b9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ * chore: Updated `LICENSE` with major contributors [#100](https://github.com/Floating-Dartists/matomo-tracker/pull/100) * chore: Added a contribution guide [#101](https://github.com/Floating-Dartists/matomo-tracker/pull/101) * refacto: Added default values to `TrackingOrderItem` [#102](https://github.com/Floating-Dartists/matomo-tracker/pull/102) - * refacto: Uniformized the "track" methods parameters [#103]() + * refacto: Uniformized the "track" methods parameters [#106](https://github.com/Floating-Dartists/matomo-tracker/pull/106) _Special thanks to [Eric Prokop](https://github.com/EPNW-Eric) who greatly contributed to this release._ From 787eb1d36760d4301c64033f61b2df02ef564ca6 Mon Sep 17 00:00:00 2001 From: Guillaume Roux Date: Sat, 3 Jun 2023 23:45:39 +0200 Subject: [PATCH 3/3] doc: added some documentation --- lib/src/matomo_action.dart | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/lib/src/matomo_action.dart b/lib/src/matomo_action.dart index a9b1d7e..da4343c 100644 --- a/lib/src/matomo_action.dart +++ b/lib/src/matomo_action.dart @@ -52,19 +52,32 @@ class MatomoAction { /// specific page view. final String? screenId; + /// If specified, the tracking request will trigger a conversion for the + /// [goal](https://matomo.org/guide/reports/goals-and-conversions/) of the + /// website being tracked with this ID. final int? goalId; + + /// The unique string identifier for the ecommerce order (required when + /// tracking an ecommerce order) final String? orderId; + + /// Items in the Ecommerce order. final List? trackingOrderItems; /// Used either as a monetary value when tracking a goal or as the total of /// an ecommerce order. final double? revenue; - /// Excludes shipping + /// Sub total of an order; excludes shipping. final num? subTotal; + /// Tax amount of an order. final num? taxAmount; + + /// Shipping cost of an order. final num? shippingCost; + + /// Discount offered for an order. final num? discountAmount; /// The current time.