Rtux Integration Php Laravel Package

Getting Started

Minimal Steps

1. Clone the Repository

   git clone https://github.com/boxalino/rtux-integration-php.git
   cd rtux-integration-php
   

2. Configure .env Copy .env.dist to .env and populate with your Boxalino API credentials, data index URL, and other required settings:

   BOXALINO_API_KEY=your_api_key_here
   BOXALINO_DATA_INDEX_URL=https://your-data-index.boxalino.com
   BOXALINO_LAYOUT_BLOCKS=your_layout_blocks_config
   

3. Set Up Docker Environment Run the CLI container to install dependencies:

   docker-compose run --rm cli-setup /bin/bash -c "composer install"
   

4. First Use Case: Fetching Raw JSON Response Use the provided RtuxClient class to make an API call. Example:

   use Boxalino\RtuxIntegration\Client\RtuxClient;
   
   $client = new RtuxClient(
       env('BOXALINO_API_KEY'),
       env('BOXALINO_DATA_INDEX_URL')
   );
   
   $response = $client->getSessionData('session_id_here');
   $rawJson = json_encode($response->getData());
   

Implementation Patterns

Core Workflows

1. Session Data Retrieval Fetch raw session data for analysis:

   $sessionData = $client->getSessionData($sessionId);
   $events = $sessionData->getEvents(); // Access nested data
   

2. Event Filtering Filter events by type or timestamp:

   $filteredEvents = $client->filterEvents($sessionData, 'click', '2024-01-01');
   

3. Layout Block Integration Map Boxalino layout blocks to your frontend:

   $layoutBlocks = $client->getLayoutBlocks();
   foreach ($layoutBlocks as $block) {
       // Integrate with your UI (e.g., track clicks on block IDs)
   }
   

Integration Tips

• Laravel Service Provider Bind the RtuxClient to the container for dependency injection:

  // app/Providers/AppServiceProvider.php
  public function register()
  {
      $this->app->singleton(RtuxClient::class, function ($app) {
          return new RtuxClient(
              config('boxalino.api_key'),
              config('boxalino.data_index_url')
          );
      });
  }
  

• Middleware for Session Tracking Attach a middleware to capture user sessions:

  // app/Http/Middleware/TrackRtuxSession.php
  public function handle($request, Closure $next)
  {
      $sessionId = $request->session()->getId();
      // Log or forward to Boxalino
      return $next($request);
  }
  

• Queue Jobs for Async Processing Offload heavy data processing to queues:

  // app/Jobs/ProcessRtuxData.php
  public function handle()
  {
      $client = app(RtuxClient::class);
      $data = $client->getSessionData($this->sessionId);
      // Process and store data
  }
  

Gotchas and Tips

Pitfalls

1. API Rate Limits

   • The Boxalino API may throttle requests. Implement exponential backoff:

     try {
         $response = $client->getSessionData($sessionId);
     } catch (RateLimitException $e) {
         sleep($e->getRetryAfter());
         retry();
     }
     

2. Session ID Mismatches

   • Ensure session IDs match between your app and Boxalino. Validate IDs before API calls:

     if (!preg_match('/^[a-f0-9]{32}$/', $sessionId)) {
         throw new InvalidArgumentException('Invalid session ID format');
     }
     

3. Raw JSON Handling

   • The package returns raw JSON responses. Sanitize data before use:

     $data = json_decode($rawJson, true);
     if (json_last_error() !== JSON_ERROR_NONE) {
         throw new RuntimeException('Invalid JSON response');
     }
     

Debugging

• Enable API Logging Configure the RtuxClient to log requests/responses:

  $client = new RtuxClient(
      env('BOXALINO_API_KEY'),
      env('BOXALINO_DATA_INDEX_URL'),
      ['logger' => new MonologLogger()] // Use Laravel's Log facade
  );
  

• Docker Debugging Access the CLI container for debugging:

  docker-compose run --rm cli-setup /bin/bash
  

Extension Points

1. Custom Response Transformers Extend the Response class to format data for your needs:

   class CustomResponse extends \Boxalino\RtuxIntegration\Response
   {
       public function toArray()
       {
           return [
               'events' => array_map(fn($e) => $e->toCustomArray(), $this->events),
           ];
       }
   }
   

2. Event Listeners Hook into Boxalino events (e.g., session start/end) via Laravel events:

   // app/Providers/EventServiceProvider.php
   protected $listen = [
       \Boxalino\RtuxIntegration\Events\SessionStarted::class => [
           \App\Listeners\LogSessionStart::class,
       ],
   ];
   

3. Testing Mock the RtuxClient in tests:

   $mock = Mockery::mock(RtuxClient::class);
   $mock->shouldReceive('getSessionData')
        ->andReturn(new \Boxalino\RtuxIntegration\Response(['test' => 'data']));
   $this->app->instance(RtuxClient::class, $mock);