Anonlytics Bundle Laravel Package

Getting Started

Minimal Setup

1. Register for Anonlytics Create a free account at anonlytics.eu to obtain your client_token and site_token.

2. Install the Bundle

   composer require defixit/anonlytics-bundle
   

3. Configure the Bundle Add the bundle to config/bundles.php:

   DeFixIT\AnonlyticsBundle\AnonlyticsBundle::class => ['all' => true],
   

4. Set Environment Variables Add to .env:

   ANONLYTICS_CLIENT_TOKEN=your_client_token_here
   ANONLYTICS_SITE_TOKEN=your_site_token_here
   

5. Create Configuration File Create config/packages/anonlytics.yaml:

   anonlytics:
     client_token: '%env(resolve:ANONLYTICS_CLIENT_TOKEN)%'
     site_token: '%env(resolve:ANONLYTICS_SITE_TOKEN)%'
   

6. First Event Tracking Inject the AnonlyticsClient service and track a page view:

   use DeFixIT\AnonlyticsBundle\Client\AnonlyticsClient;
   
   public function someAction(AnonlyticsClient $anonlytics)
   {
       $anonlytics->trackPageView('/home');
   }
   

Implementation Patterns

Core Workflows

1. Page View Tracking

Track page views with optional metadata:

$anonlytics->trackPageView('/dashboard', [
    'user_id' => $user->id,
    'referrer' => $request->headers->get('referer'),
]);

2. Event Tracking

Log custom events (e.g., button clicks, form submissions):

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

3. User Identification (GDPR-Compliant)

Anonymously associate events with a user session (no PII stored):

$anonlytics->identifyUser($user->id); // Uses a hashed/salted identifier

4. Integration with Symfony Events

Listen to kernel events (e.g., kernel.request) to auto-track routes:

// src/EventListener/AnonlyticsListener.php
public function onKernelRequest(GetResponseEvent $event)
{
    $request = $event->getRequest();
    $anonlytics->trackPageView($request->getPathInfo());
}

5. Batch Processing

For performance, batch events before sending:

$anonlytics->addEvent(['type' => 'page_view', 'path' => '/contact']);
$anonlytics->addEvent(['type' => 'event', 'name' => 'form_submitted']);
// Later, flush all events:
$anonlytics->flush();

Advanced Patterns

Dynamic Token Management

Override tokens per environment (e.g., staging/production):

# config/packages/dev/anonlytics.yaml
anonlytics:
  client_token: '%env(resolve:ANONLYTICS_CLIENT_TOKEN_DEV)%'
  site_token: '%env(resolve:ANONLYTICS_SITE_TOKEN_DEV)%'

Middleware for Auto-Tracking

Create middleware to track all requests:

// src/Middleware/AnonlyticsMiddleware.php
public function handle(Request $request, Closure $next)
{
    $response = $next($request);
    $this->anonlytics->trackPageView($request->getPathInfo());
    return $response;
}

Custom Dimensions

Extend tracking with custom dimensions (e.g., user segments):

$anonlytics->setUserProperties([
    'segment' => 'premium',
    'plan' => 'annual',
]);

Gotchas and Tips

Pitfalls

1. Token Validation

   • Issue: Silent failures if client_token/site_token are invalid.
   • Fix: Enable debug mode or wrap calls in a try-catch:

     try {
         $anonlytics->trackEvent('test');
     } catch (\RuntimeException $e) {
         $this->logger->error('Anonlytics failed: '.$e->getMessage());
     }
     

2. Rate Limiting

   • Issue: High-frequency events may trigger rate limits.
   • Fix: Use batching (addEvent() + flush()) or throttle calls.

3. GDPR Compliance

   • Issue: Accidentally sending PII (e.g., email, IP).
   • Fix: Never pass raw user data. Use hashed IDs or metadata only.

4. Configuration Overrides

   • Issue: Tokens not updating after .env changes.
   • Fix: Clear cache (php bin/console cache:clear) or use cache:pool:clear anonlytics.

Debugging Tips

1. Enable Debug Logging Add to config/packages/dev/anonlytics.yaml:

   anonlytics:
     debug: true
   

   Check logs for failed requests.

2. Test Locally with Mock Tokens Use a test account’s tokens in .env to verify events are sent:

   ANONLYTICS_CLIENT_TOKEN=test_client_token
   ANONLYTics_SITE_TOKEN=test_site_token
   

3. Validate Events Use the Anonlytics Dashboard to confirm events appear in real-time.

Extension Points

1. Custom Event Types Extend the client to support custom event schemas:

   // src/Service/ExtendedAnonlyticsClient.php
   public function trackCustomEvent(string $type, array $data): void
   {
       $this->client->addEvent([
           'type' => 'custom_'.$type,
           'data' => $data,
       ]);
   }
   

2. Event Transformers Transform data before sending (e.g., sanitize or normalize):

   $anonlytics->setEventTransformer(function (array $event) {
       return array_map('strtolower', $event);
   });
   

3. Async Processing Use Symfony Messenger to queue events for background processing:

   $message = new AnonlyticsEvent($eventData);
   $this->messageBus->dispatch($message);
   

4. Environment-Specific Tokens Use %kernel.environment% in anonlytics.yaml to switch tokens:

   anonlytics:
     client_token: '%env(resolve:ANONLYTICS_TOKEN_%kernel.environment%)%'