README

Currently under testing for official release - 4.4.2024

Laravel A/B by Pivotal is a package to help you create and manage A/B tests on your laravel blade templates. It also provides a way to generate and view reports locally or by integration into Pivotal AB services.

Installation

You can install the package via composer:

composer require pivotalso/pivotal-ab

Add the service provider in config/app.php:

    'providers' => ServiceProvider::defaultProviders()->merge([
        ...
        pivotalso\PivotalAb\PivotalAbServiceProvider::class,
    ]),

If you want to send your events to Pivotal AB, you must configure the library to listen for save events. Add the following to your EventServiceProvider:

  ....
  use pivotalso\PivotalAb\Events\Track;
  use pivotalso\PivotalAb\Listeners\TrackerLogger;
  
  class EventServiceProvider extends ServiceProvider {
       protected $listen = [
        ...,
        Track::class => [
            TrackerLogger::class,
        ],
    ];

as well as add LARAVEL_AB_API_KEY to your .env file You can get your api key from your project settings page on Pivotal AB.

You can publish and run the migrations with:

php artisan vendor:publish --tag="ab-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="ab-config"

/// ab.php
return [
    'cache_key' => 'laravel_ab_user',
    'request_param'=> env('LARAVEL_AB_REQUEST_PARAM', 'abid'), /// listen for query string param to override instance id
    'allow_param'=> env('LARAVEL_AB_ALLOW_PARAM', false), /// allows for the use of request param
    'api_key' => env('LARAVEL_AB_API_KEY', ''), // the api key for pivotal intelligence
];

Documentation

You can find the documentation for this package at https://docs.pivotal.so/docs/ab/laravel

Usage

Here is an example use case of a nested A/B test tracking signup and free trial goals

welcome.blade.php

<html>
    <head>
        <title>My Website</title>
    </head>
    <body>
        @ab('hero-text')
        @condtion('my website')
            <h1>My Website</h1>
        @condition('welcome user')
            <h1>Welcome, {{ $user->name }}</h1> 
                  @ab('free offer for new users')
                    @condtion('free trial')
                        <button>Start your free trial</button>
                    @condition('get started')
                        <button>Get Started</button>      
                    @track('free trial')       
        @track('sign up')
    </body>
</html

You can also easily test logic within you Controllers

class PagesController extends Controller
{
    public function welcome()
    {
       $option =  
       Ab::choice('kind of homepage', ['control', 'variant'])->track('go-to-ab');
       if ($option === 'variant') {
           return view('variant-welcome');
        }
       return view('welcome');
    }

You can either track goals in views or within your application logic. register.blade.php

<html>
    <head>
        <title>My Website</title>
    </head>
    <body>
        .... body
        @goal('sign up')
    </body>
</html

or for example RegistrationController.php

    public function store(Request $request)
    {
        .... store logic
        PivotalAb::goal('sign up');
        if($request->has('free_trial')) {
            PivotalAb::goal('free trial');
        }
    }

Reporting

You can view reports locally by running the following command

php artisan ab:report

a sample output would be

{
    "hero-text": [
        {
            "condition": "my website",
            "hits": 6,
            "goals": 3,
            "conversion": 50
        },
        {
            "condition": "welcome user",
            "hits": 12,
            "goals": 3,
            "conversion": 25
        }
    ]
}

You can also see report on your browser if you specify a reporting url, username, and password

LARAVEL_AB_REPORT_URL='/hidden/ab/reports'
LARAVEL_AB_REPORT_USERNAME='user123'
LARAVEL_AB_REPORT_PASSWORD='password123'

You can then visit http://yourapp.com/hidden/ab/reports to view your reports

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

Rulian Estivalletti

License

The MIT License (MIT). Please see License File for more information.

pivotalso / pivotal-ab

Maintainers

Details