Merge pull request #4 from placetopay-org/feature/add-should-track-ev…

…ents-property

Feature/add should track events property

CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.1.0] - 2024-08-02
+
+### Added
+
+- Add `shouldTrackEvents` method to `AnalyticsTracker` contract.
+
 ## [1.0.1] - 2024-04-26
 
 ### Changed

README.md

@@ -30,6 +30,24 @@ Add the following variables to your .env:
 use Placetopay\AnalyticsTracker\Facades\Analytics;
 
 Analytics::setIdentifier("user@company.com") // (optional) Associate a user to the tracked events
-->setDefaultPayload(['key' => 'value']) // Set the default data to be sent on every track call
-->track('Label', ['key' => 'value']); // Tracks an event
+    ->setDefaultPayload(['key' => 'value']) // Set the default data to be sent on every track call
+    ->track('Label', ['key' => 'value']); // Tracks an event
+```
+
+## Conditional tracking
+
+You may call the `shouldTrackEvents` method to define a condition for when to track events. The method receives a callback that should return a boolean value.
+
+```php
+use Placetopay\AnalyticsTracker\Facades\Analytics;
+
+Analytics::setIdentifier("user@company.com")
+    ->shouldTrackEvents(fn($label, $payload) => $payload['siteId'] === '1234')
+    ->track('Label', ['siteId' => '5678']);
+
+
+Analytics::setIdentifier("user@company.com")
+    ->shouldTrackEvents(new InvokableClass()) // May use an Invokable class 
+    ->track('Label', ['siteId' => '5678']);
+
 ```

src/Contracts/AnalyticsTracker.php

@@ -8,5 +8,7 @@ public function track(string $label, array $payload = []);
 
     public function setDefaultPayload(array $payload): self;
 
+    public function shouldTrackEvents(callable $shouldTrackEvents): self;
+
     public function setIdentifier(string $identifier): self;
 }

src/Trackers/MixpanelTracker.php

@@ -2,13 +2,15 @@
 
 namespace Placetopay\AnalyticsTracker\Trackers;
 
+use Closure;
 use Mixpanel;
 use Placetopay\AnalyticsTracker\Contracts\AnalyticsTracker;
 
 class MixpanelTracker implements AnalyticsTracker
 {
     private ?Mixpanel $mixpanel = null;
     private array $defaultPayload = [];
+    private ?Closure $shouldTrackEvents = null;
 
     public function __construct()
     {
@@ -26,7 +28,20 @@ public function __construct()
 
     public function track(string $label, array $payload = []): void
     {
-        $this->mixpanel?->track($label, array_merge($this->defaultPayload, $payload));
+        if ($this->mixpanel === null) {
+            return;
+        }
+
+        if ($this->shouldTrack($label, $payload)) {
+            $this->mixpanel->track($label, array_merge($this->defaultPayload, $payload));
+        }
+    }
+
+    private function shouldTrack(string $label, array $payload = [])
+    {
+        return is_callable($this->shouldTrackEvents)
+            ? ($this->shouldTrackEvents)($label, $payload)
+            : true;
     }
 
     public function setDefaultPayload(array $payload): self
@@ -35,6 +50,13 @@ public function setDefaultPayload(array $payload): self
         return $this;
     }
 
+    public function shouldTrackEvents(callable $shouldTrackEvents): self
+    {
+        $this->shouldTrackEvents = $shouldTrackEvents(...);
+
+        return $this;
+    }
+
     private function enabled(): bool
     {
         return config('analytics-tracker.mixpanel.enabled');

tests/Unit/Trackers/MixpanelTrackerTest.php

@@ -101,6 +101,69 @@ public function it_does_not_track_when_disabled(): void
         $mixpanelTracker->track($label);
     }
 
+    /**
+     * @test
+     */
+    public function it_decides_to_track_events_with_function(): void
+    {
+        $mixpanelMock = $this->createMock(Mixpanel::class);
+        $mixpanelMock->expects($this->once())
+            ->method('track')
+            ->with('EventTracked', ['prop1' => 'value1']);
+
+        $this->app->offsetSet(Mixpanel::class, $mixpanelMock);
+
+        $shouldTrackEvent = function (string $label, array $payload) {
+            $this->assertArrayHasKey('prop1', $payload);
+
+            return $label === 'EventTracked';
+        };
+
+        $mixpanelTracker = (new MixpanelTracker())->shouldTrackEvents($shouldTrackEvent);
+        $mixpanelTracker->track('EventDropped', ['prop1' => 'value1']);
+        $mixpanelTracker->track('EventTracked', ['prop1' => 'value1']);
+    }
+
+    /**
+     * @test
+     */
+    public function it_decides_to_track_events_with_an_invokable(): void
+    {
+        $mixpanelMock = $this->createMock(Mixpanel::class);
+        $mixpanelMock->expects($this->once())
+            ->method('track')
+            ->with('EventTracked', ['prop1' => 'value1']);
+
+        $this->app->offsetSet(Mixpanel::class, $mixpanelMock);
+
+        $shouldTrackEvent = new class {
+            public function __invoke(string $label, array $payload)
+            {
+                return $label === 'EventTracked';
+            }
+        };
+
+        $mixpanelTracker = (new MixpanelTracker())->shouldTrackEvents($shouldTrackEvent);
+        $mixpanelTracker->track('EventDropped', ['prop1' => 'value1']);
+        $mixpanelTracker->track('EventTracked', ['prop1' => 'value1']);
+    }
+
+    /**
+     * @test
+     */
+    public function it_does_not_track_when_should_not_track_events(): void
+    {
+        $mixpanelMock = $this->createMock(Mixpanel::class);
+        $mixpanelMock->expects($this->never())
+            ->method('track')
+            ->with('EventDropped', ['prop1' => 'value1']);
+
+        $this->app->offsetSet(Mixpanel::class, $mixpanelMock);
+
+        $mixpanelTracker = (new MixpanelTracker())->shouldTrackEvents(fn () => false);
+        $mixpanelTracker->track('EventDropped', ['prop1' => 'value1']);
+    }
+
     /**
      * @test
      */