Tracker Hub Laravel Package

Getting Started

First Steps

1. Installation

   composer require beeketing/tracker-hub
   

   Ensure beeketing/tracker-hub is listed in config/app.php under providers.

2. Publish Config

   php artisan vendor:publish --provider="Beeketing\TrackerHub\TrackerHubServiceProvider" --tag="config"
   

   This generates config/tracker-hub.php. Review the default settings (e.g., API keys, allowed trackers).

3. Environment Setup Add your API keys to .env (e.g., TRACKER_HUB_API_KEY=your_key_here).

4. Basic Usage

   use Beeketing\TrackerHub\Facades\TrackerHub;
   
   // Track a page view
   TrackerHub::trackPageView('homepage');
   
   // Track a custom event
   TrackerHub::trackEvent('user_signup', ['email' => 'user@example.com']);
   

5. Middleware Integration Add the Beeketing\TrackerHub\Http\Middleware\TrackPageViews middleware to your app/Http/Kernel.php:

   protected $middleware = [
       // ...
       \Beeketing\TrackerHub\Http\Middleware\TrackPageViews::class,
   ];
   

Implementation Patterns

Core Workflows

1. Page View Tracking

   • Automatically track page views via middleware (e.g., TrackPageViews).
   • Customize tracked data in app/Http/Middleware/TrackPageViews.php:

     public function handle($request, Closure $next) {
         TrackerHub::trackPageView($request->path(), [
             'referrer' => $request->header('referer'),
             'user_agent' => $request->userAgent(),
         ]);
         return $next($request);
     }
     

2. Event Tracking

   • Use trackEvent() for custom events (e.g., button clicks, form submissions):

     TrackerHub::trackEvent('checkout_started', [
         'product_id' => $product->id,
         'value' => $product->price,
     ]);
     

3. User Identification

   • Attach user data to events:

     if (auth()->check()) {
         TrackerHub::identifyUser(auth()->id(), auth()->user()->email);
     }
     

4. Batch Processing

   • Queue events for async processing (if supported):

     TrackerHub::queueEvent('purchase_completed', ['order_id' => 123]);
     

Integration Tips

• Laravel Scout Sync: If using Scout, extend Beeketing\TrackerHub\ScoutEngine to sync data.

• Blade Directives: Create a @track directive for inline tracking:

  Blade::directive('track', function ($event) {
      return "<?php \\Beeketing\\TrackerHub\\Facades\\TrackerHub::trackEvent('{$event[0]}', ".json_encode($event[1] ?? []).'); ?>";
  });
  

  Usage:

  @track(['button_click', ['button_id' => 'cta']])
  

• API Routes: Expose a /track endpoint for frontend JS tracking:

  Route::post('/track', function (Request $request) {
      TrackerHub::trackEvent($request->event, $request->data);
      return response()->json(['success' => true]);
  });
  

Gotchas and Tips

Pitfalls

1. API Key Leaks

   • Never hardcode API keys in Blade templates or client-side JS. Use server-side tracking only.
   • Validate .env is in .gitignore.

2. Rate Limiting

   • The package may throttle requests. Monitor config/tracker-hub.php for max_retries and timeout settings.

3. Data Sanitization

   • Ensure sensitive data (e.g., PII) is never sent to trackers. Use config/tracker-hub.php to whitelist allowed fields:

     'allowed_event_fields' => ['product_id', 'category', 'value'],
     

4. Middleware Order

   • Place TrackPageViews after StartSession and Authenticate to access $request data.

Debugging

• Log Events: Enable debug mode in config/tracker-hub.php:

  'debug' => env('TRACKER_HUB_DEBUG', false),
  

  Logs will appear in storage/logs/laravel.log.

• Test Locally: Use a mock tracker (e.g., TrackerHub::setMockMode(true)) to verify events before going live.

Extension Points

1. Custom Trackers

   • Extend Beeketing\TrackerHub\Contracts\Tracker to add support for new analytics platforms:

     class CustomTracker implements Tracker {
         public function track($event, array $data) {
             // Custom logic (e.g., HTTP requests to your own endpoint)
         }
     }
     

   • Register in config/tracker-hub.php:

     'trackers' => [
         'custom' => \App\Services\CustomTracker::class,
     ],
     

2. Event Transformers

   • Modify event data before sending:

     TrackerHub::extend(function ($event, $data) {
         $data['processed_at'] = now()->toIso8601String();
         return $data;
     });
     

3. Webhook Listeners

   • Listen for tracker responses:

     TrackerHub::onResponse(function ($response) {
         Log::info('Tracker response', $response->toArray());
     });