Adback Analytics Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Package

   composer require dekalee/adback-analytics-bundle
   

   Ensure AdBackAnalyticsBundle is enabled in config/bundles.php:

   Dekalee\AdbackAnalyticsBundle\AdbackAnalyticsBundle::class => ['all' => true],
   

2. Configure the Bundle Publish the default config and adjust:

   php artisan vendor:publish --provider="Dekalee\AdbackAnalyticsBundle\AdbackAnalyticsBundle" --tag="config"
   

   Update config/adback_analytics.php with your API credentials and project ID:

   return [
       'api_key' => env('ADBACK_API_KEY'),
       'project_id' => env('ADBACK_PROJECT_ID'),
       'debug' => env('APP_DEBUG', false),
   ];
   

3. First Use Case: Track a Page View Inject the AdbackAnalyticsService into a controller or service:

   use Dekalee\AdbackAnalyticsBundle\Service\AdbackAnalyticsService;
   
   public function show(AdbackAnalyticsService $adback)
   {
       $adback->trackPageView('homepage', [
           'url' => url()->current(),
           'referrer' => request()->header('referer'),
       ]);
   }
   

Implementation Patterns

Core Workflows

1. Event-Based Tracking Use Laravel events to trigger analytics automatically:

   // In an event listener
   public function handle(PageViewed $event)
   {
       $this->adback->trackEvent('page_view', [
           'page' => $event->page,
           'user_id' => auth()->id(),
       ]);
   }
   

2. Middleware for Automatic Tracking Attach middleware to routes or globally to log visits:

   namespace App\Http\Middleware;
   
   use Closure;
   use Dekalee\AdbackAnalyticsBundle\Service\AdbackAnalyticsService;
   
   class TrackVisits
   {
       public function __construct(private AdbackAnalyticsService $adback) {}
   
       public function handle($request, Closure $next)
       {
           $this->adback->trackPageView('route', [
               'path' => $request->path(),
               'method' => $request->method(),
           ]);
           return $next($request);
       }
   }
   

3. User-Specific Tracking Attach user metadata to events:

   $this->adback->trackEvent('user_action', [
       'action' => 'purchase',
       'user_id' => auth()->id(),
       'email' => auth()->user()->email,
       'value' => $order->total,
   ]);
   

Integration Tips

• Queue Delayed Requests Offload analytics calls to a queue to avoid blocking user requests:

  $this->adback->queueTrackEvent('delayed_event', $data);
  

  Configure the queue in config/adback_analytics.php:

  'queue' => [
      'enabled' => true,
      'connection' => 'database',
  ],
  

• Batch Processing Use Laravel's task scheduling to batch and send analytics in bulk:

  // app/Console/Commands/SendAdbackBatch.php
  public function handle()
  {
      $this->adback->flushQueue();
  }
  

  Schedule it in app/Console/Kernel.php:

  $schedule->command('adback:flush')->hourly();
  

Gotchas and Tips

Pitfalls

1. API Rate Limits AdBack may throttle requests. Monitor your config/adback_analytics.php max_retries and adjust:

   'retry' => [
       'max_attempts' => 3,
       'delay' => 1000, // ms
   ],
   

2. Sensitive Data Exposure Avoid logging PII (Personally Identifiable Information) in analytics. Use hashed IDs or omit sensitive fields:

   // Bad: $this->adback->trackEvent('login', ['email' => $user->email]);
   // Good: $this->adback->trackEvent('login', ['user_id' => $user->id]);
   

3. Debugging Failed Requests Enable debug mode in config to log errors:

   'debug' => true,
   

   Check Laravel logs (storage/logs/laravel.log) for failed API calls.

Tips

• Custom Event Names Use consistent, lowercase event names with underscores for readability:

  $this->adback->trackEvent('user_signup_success', $data);
  

• Extend the Service Create a decorator to add custom logic:

  namespace App\Services;
  
  use Dekalee\AdbackAnalyticsBundle\Service\AdbackAnalyticsService;
  
  class CustomAdbackAnalyticsService extends AdbackAnalyticsService
  {
      public function trackCustomEvent(string $name, array $data)
      {
          $data['custom_flag'] = true;
          $this->trackEvent($name, $data);
      }
  }
  

  Bind it in AppServiceProvider:

  $this->app->bind(
      AdbackAnalyticsService::class,
      CustomAdbackAnalyticsService::class
  );
  

• Environment-Specific Config Use .env to toggle features per environment:

  ADBACK_ENABLED=true
  ADBACK_DEBUG=false
  

  Add a check in your service:

  if (!config('adback.enabled')) {
      return;
  }
  

• Testing Mock the service in tests to avoid real API calls:

  $mock = Mockery::mock(AdbackAnalyticsService::class);
  $mock->shouldReceive('trackEvent')->once();
  $this->app->instance(AdbackAnalyticsService::class, $mock);