Skip to content

Commit

Permalink
Merge pull request #106 from Floating-Dartists/refacto/uniformize-tra…
Browse files Browse the repository at this point in the history 
…cking-methods

refacto: uniformized and enforced parameters of tracking methods
  • Loading branch information
@TesteurManiak
TesteurManiak authored Jun 3, 2023
2 parents d78de81 + 787eb1d commit a4e13c7
Show file tree
Hide file tree
Showing 5 changed files with 95 additions and 79 deletions.
4 changes: 4 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 [#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._

Expand Down
6 changes: 6 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
122 changes: 56 additions & 66 deletions lib/src/matomo.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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<String, String>? dimensions,
bool? newVisit,
Expand All @@ -533,7 +531,7 @@ class MatomoTracker {
validateDimension(dimensions);
return _track(
MatomoAction(
goalId: goalId,
goalId: id,
revenue: revenue,
dimensions: dimensions,
newVisit: _inferNewVisit(newVisit),
Expand All @@ -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,
Expand All @@ -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<String, String> dimensions, {
void trackDimensions({
required Map<String, String> dimensions,
bool? newVisit,
}) {
validateDimension(dimensions);
Expand All @@ -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,
Expand All @@ -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<TrackingOrderItem>? trackingOrderItems,
num? subTotal,
num? taxAmount,
num? shippingCost,
num? discountAmount, {
num? discountAmount,
Map<String, String>? dimensions,
bool? newVisit,
}) {
Expand All @@ -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,
Expand All @@ -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<TrackingOrderItem>? trackingOrderItems,
num? revenue,
num? subTotal,
num? taxAmount,
num? shippingCost,
num? discountAmount, {
num? discountAmount,
Map<String, String>? dimensions,
bool? newVisit,
}) {
Expand All @@ -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,
Expand All @@ -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<String, String>? dimensions,
bool? newVisit,
}) {
Expand All @@ -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,
Expand Down Expand Up @@ -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,
Expand Down
22 changes: 19 additions & 3 deletions lib/src/matomo_action.dart
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,16 +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<TrackingOrderItem>? trackingOrderItems;
final num? revenue;

/// Excludes shipping
/// Used either as a monetary value when tracking a goal or as the total of
/// an ecommerce order.
final double? revenue;

/// 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.
Expand Down Expand Up @@ -100,7 +116,7 @@ class MatomoAction {
int? goalId,
String? orderId,
List<TrackingOrderItem>? trackingOrderItems,
num? revenue,
double? revenue,
num? subTotal,
num? taxAmount,
num? shippingCost,
Expand Down
Loading

0 comments on commit a4e13c7

Please sign in to comment.