Adback Analytics Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require dekalee/adback-analytics
   

   Register the service provider in config/app.php under providers:

   Dekalee\AdbackAnalytics\AdbackAnalyticsServiceProvider::class,
   

2. Configuration Publish the config file:

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

   Update config/adback.php with your API credentials (client ID, secret, and environment).

3. First Use Case: Fetching Campaign Data Inject the AdbackAnalytics facade or service into a controller/service:

   use Dekalee\AdbackAnalytics\Facades\AdbackAnalytics;
   
   public function getCampaigns()
   {
       $campaigns = AdbackAnalytics::campaigns()->fetch();
       return response()->json($campaigns);
   }
   

Implementation Patterns

Core Workflows

1. API Resource Fetching Use fluent methods to retrieve data:

   // Get all campaigns
   $campaigns = AdbackAnalytics::campaigns()->fetch();
   
   // Filter by date range
   $campaigns = AdbackAnalytics::campaigns()
       ->dateRange('2023-01-01', '2023-12-31')
       ->fetch();
   
   // Pagination
   $campaigns = AdbackAnalytics::campaigns()->perPage(20)->fetch();
   

2. Authentication & Rate Limiting Handle token refresh automatically via middleware:

   // In routes/web.php or routes/api.php
   Route::middleware(['adback.auth'])->group(function () {
       // Protected routes
   });
   

   Configure rate limits in config/adback.php:

   'rate_limits' => [
       'max_attempts' => 5,
       'decay_minutes' => 1,
   ],
   

3. Webhook Integration Validate and process Adback webhooks:

   use Dekalee\AdbackAnalytics\Webhook;
   
   public function handleWebhook(Request $request)
   {
       $payload = $request->getContent();
       $webhook = new Webhook($payload);
   
       if ($webhook->isValid()) {
           $event = $webhook->parse();
           // Process event (e.g., update DB, trigger jobs)
       }
       return response()->json(['status' => 'processed']);
   }
   

4. Batch Processing Use chunking for large datasets:

   $campaigns = AdbackAnalytics::campaigns()->fetch();
   foreach ($campaigns as $campaign) {
       // Process in chunks of 100
       AdbackAnalytics::campaigns()->chunk(100, function ($chunk) {
           foreach ($chunk as $item) {
               // Handle each item
           }
       });
   }
   

Gotchas and Tips

Common Pitfalls

1. Token Expiry Handling

   • Issue: Silent failures if the access token expires without refresh.
   • Fix: Enable debug mode in config/adback.php to log token errors:

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

   • Workaround: Implement a retry mechanism for failed requests:

     try {
         $data = AdbackAnalytics::campaigns()->fetch();
     } catch (\Dekalee\AdbackAnalytics\Exceptions\TokenExpiredException $e) {
         AdbackAnalytics::refreshToken();
         $data = AdbackAnalytics::campaigns()->fetch();
     }
     

2. Pagination Quirks

   • Issue: Some endpoints may not respect perPage() if the API has hidden limits.
   • Tip: Check the raw response for pagination metadata:

     $response = AdbackAnalytics::campaigns()->fetch();
     $meta = $response->getMeta(); // Inspect for 'total_pages'
     

3. Webhook Validation

   • Issue: False positives in webhook signature validation.
   • Tip: Verify the Adback-Signature header matches the payload:

     $webhook = new Webhook($payload, $request->header('Adback-Signature'));
     if (!$webhook->isValid()) {
         abort(403, 'Invalid webhook signature');
     }
     

4. Rate Limiting

   • Issue: Throttling during bulk operations.
   • Tip: Use exponential backoff in custom implementations:

     $attempts = 0;
     while ($attempts < 3) {
         try {
             $result = AdbackAnalytics::customEndpoint()->fetch();
             break;
         } catch (\Dekalee\AdbackAnalytics\Exceptions\RateLimitException $e) {
             $attempts++;
             sleep(2 ** $attempts); // Exponential backoff
         }
     }
     

Extension Points

1. Custom Endpoints Extend the API client for unsupported endpoints:

   use Dekalee\AdbackAnalytics\AdbackClient;
   
   $client = new AdbackClient();
   $response = $client->get('/custom/endpoint', [
       'query' => ['param' => 'value']
   ]);
   

2. Event Listeners Subscribe to Adback events (e.g., adback.token.refreshed):

   // In EventServiceProvider
   protected $listen = [
       'adback.token.refreshed' => [
           \App\Listeners\LogTokenRefresh::class,
       ],
   ];
   

3. Mocking for Testing Use the AdbackAnalytics facade with a mock client:

   $this->mock(AdbackAnalytics::class)->shouldReceive('campaigns')
       ->andReturnSelf()
       ->shouldReceive('fetch')
       ->andReturn([/* mock data */]);
   

4. Logging Enable request/response logging in config/adback.php:

   'logging' => [
       'enabled' => true,
       'path' => storage_path('logs/adback.log'),
   ],