Introduction

When you're building a website or an app, knowing how users interact with it is key to improving the experience. However, many tracking tools are complicated, costly, or don't care about privacy. That's where Pan steps in. Pan is a simple, privacy-friendly tool for tracking user behavior on your Laravel app, created by Nuno Maduro and David Hill from the Laravel team.

In this guide, I'll show you how to integrate Pan into your Laravel project and track things like views, hovers, and clicks without collecting personal data from your users.

What You'll Need

Before we jump in, make sure you have the following ready:

• PHP 8.3 or higher
• A Laravel 11+ project set up
• Composer installed (helps manage your project dependencies)

Check out this intro video by Josh Cirre:

Step 1 — Installing Pan

First up, let's add Pan to your Laravel project. You’ll do this using Composer:

1. Open your terminal.
2. Navigate to your Laravel project folder.
3. Run this command:

composer require panphp/pan

This will install Pan into your project.

1. Now, run this command to set up Pan:

php artisan install:pan

This command will configure everything for you!

Step 2 — Track User Actions

With Pan installed, you can now track parts of your website. Pan uses a data-pan attribute to track specific elements.

For example, to track when someone clicks or hovers over a "Sign Up" button, you’d add this:

<button data-pan="sign-up-button">Sign Up</button>

Here are more examples:

<div data-pan="hero-section">Welcome to our site!</div>
<a data-pan="learn-more-link" href="/about">Learn More</a>
<form data-pan="contact-form">
  <!-- Your form fields here -->
</form>

Pan will automatically start tracking impressions, hovers, and clicks for these elements!

Step 3 — View Your Tracking Data

Now that Pan is tracking your elements, you can view the data it collects using Artisan:

1. Open your terminal.
2. Go to your project folder.
3. Run this command:

php artisan pan

You'll get a table showing how many times each element has been viewed, hovered over, or clicked.

If you want to check a specific element, use:

php artisan pan --filter=sign-up-button

Replace sign-up-button with the element you’re tracking.

Step 4 — Customize Pan (Optional)

By default, Pan tracks up to 50 elements, but you can change this if needed. To customize Pan, open the AppServiceProvider.php file and add:

use Pan\PanConfiguration;

public function register(): void
{
    // Track specific elements
    PanConfiguration::allowedAnalytics([
        'sign-up-button',
        'contact-form',
    ]);

    // Or increase the limit
    // PanConfiguration::maxAnalytics(10000);

    // Or remove the limit entirely
    // PanConfiguration::unlimitedAnalytics();
}

Step 5 — What Pan Tracks

Here’s what Pan tracks:

1. Impressions: Counts how many times an element is seen.
2. Hovers: Counts how many times users hover over an element.
3. Clicks: Counts how many times users click on an element.

Pan is completely privacy-friendly—it doesn’t collect any personal data about your users.

Step 6 — Use the Data to Improve

With Pan tracking how users interact with your site, you can use that data to improve your site. For example:

• If a button isn’t clicked much, maybe it needs more attention or clearer text.
• If users are hovering over an element but not clicking, maybe it’s confusing.
• If some sections aren’t being viewed, think about moving them to more visible areas.

Step 7 — Clear Tracking Data

If you ever need to clear Pan's tracking data, it’s easy:

1. Open your terminal.
2. Navigate to your project folder.
3. Run this command:

php artisan pan:flush

This will reset Pan's tracking data, so you can start fresh.

Conclusion

Pan makes it easy to understand how users interact with your Laravel app without compromising their privacy.

By adding the data-pan attribute and using Artisan commands, you can track user behavior and make informed improvements to your website or app.