Userback Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require codeplace-io/userback-bundle
   

   Add to config/bundles.php:

   return [
       // ...
       Codeplace\Bundle\UserbackBundle\UserbackBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php bin/console config:dump-reference Codeplace\UserbackBundle
   

   Update .env with your Userback API key:

   USERBACK_API_KEY=your_api_key_here
   

3. First Use Case Trigger a feedback widget on a critical page (e.g., checkout):

   {% block userback_widget %}
       {{ userback_widget() }}
   {% endblock %}
   

   Verify the widget appears in your browser and logs feedback to Userback.io.

Implementation Patterns

Core Workflows

1. Widget Integration

   • Dynamic Placement: Use Twig’s userback_widget() in layouts or specific templates.
   • Conditional Rendering: Disable on admin routes:

     {% if app.request.get('_route') != 'admin_dashboard' %}
         {{ userback_widget() }}
     {% endif %}
     

2. Event Tracking

   • Custom Events: Dispatch events via the bundle’s API:

     $this->get('userback')->trackEvent('ProductViewed', ['product_id' => 123]);
     

   • Lifecycle Hooks: Integrate with Symfony events (e.g., kernel.request):

     # config/services.yaml
     services:
         App\EventListener\UserbackTracker:
             tags:
                 - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest }
     

3. User Context

   • Automatic User Mapping: Sync Symfony users to Userback:

     $this->get('userback')->setUserContext($user->getId(), $user->getEmail());
     

   • Manual Overrides: Pass custom metadata:

     $this->get('userback')->setUserContext(null, null, ['plan' => 'premium']);
     

4. API-Driven Features

   • Feedback Submission: Handle form submissions via Userback’s API:

     $this->get('userback')->submitFeedback([
         'message' => 'Bug report',
         'screenshot' => $request->file('screenshot')->getPathname(),
     ]);
     

Integration Tips

• Asset Management: Ensure Userback’s JS/CSS loads after jQuery (if required). Use Symfony’s asset pipeline or inline scripts:

  <script src="{{ asset('bundles/userback/js/userback.js') }}"></script>
  

• Environment Awareness: Disable the widget in dev:

  # config/packages/userback.yaml
  userback:
      enabled: '%kernel.debug% ? false : true'
  

Gotchas and Tips

Pitfalls

1. API Key Exposure

   • Risk: Hardcoding USERBACK_API_KEY in .env may leak in Git.
   • Fix: Use Symfony’s ParameterBag or environment variables strictly. Avoid logging the key.

2. Widget Initialization Race

   • Issue: Widget fails to load if DOM isn’t ready.
   • Fix: Defer initialization:

     document.addEventListener('DOMContentLoaded', function() {
         Userback.init({ apiKey: '{{ app.parameters.userback.api_key }}' });
     });
     

3. User Context Conflicts

   • Issue: Multiple setUserContext() calls overwrite data.
   • Fix: Merge contexts instead:

     $currentContext = $this->get('userback')->getUserContext();
     $this->get('userback')->setUserContext(
         $currentContext['userId'],
         $currentContext['email'],
         array_merge($currentContext['metadata'], ['new_key' => 'value'])
     );
     

4. CORS Restrictions

   • Issue: API calls fail if Userback’s domain isn’t whitelisted.
   • Fix: Configure CORS in config/packages/security.yaml:

     cors:
         paths:
             '^/api/userback/*':
                 allow_origin: ['https://your-userback-instance.userback.io']
     

Debugging

• Enable Logging: Add to config/packages/monolog.yaml:

  handlers:
      userback:
          type: stream
          path: "%kernel.logs_dir%/userback.log"
          level: debug
  

• Check Network Tab: Verify API calls to https://api.userback.io in browser dev tools.
• Bundle Events: Listen for userback.event to debug lifecycle:

  $eventDispatcher->addListener('userback.event', function($event) {
      error_log('Userback event: ' . $event->getName());
  });
  

Extension Points

1. Custom Feedback Forms

   • Override the default widget template:

     # templates/userback/widget.html.twig
     <div class="custom-userback-widget">
         {{ include('userback::_widget.html.twig') }}
     </div>
     

   • Extend the UserbackService to add methods:

     // src/Service/UserbackService.php
     public function trackCustomEvent(string $name, array $data): void {
         $this->client->post('/events', [
             'event' => $name,
             'data' => $data,
             'api_key' => $this->apiKey,
         ]);
     }
     

2. Webhook Handling

   • Create a controller to process Userback webhooks:

     #[Route('/userback/webhook', name: 'userback_webhook', methods: ['POST'])]
     public function handleWebhook(Request $request): Response {
         $payload = json_decode($request->getContent(), true);
         // Validate and process $payload
         return new Response('OK');
     }
     

   • Verify signatures using Userback’s X-Signature header.

3. Feature Flags

   • Dynamically toggle features via Userback’s API:

     $this->get('userback')->setFeatureFlag('new_ui', true);