esign/laravel-conversions-api

A laravel wrapper package around the Facebook Conversions API

Downloads

23

Stars

1

Version

1.1.0

Interact with the Facebook Conversions API

Latest Version on Packagist Total Downloads GitHub Actions

This package allow you to easily interact with the Facebook Conversions API.

Installation

You can install the package via composer:

composer require esign/laravel-conversions-api

Next up, you can publish the configuration file:

php artisan vendor:publish --provider="Esign\ConversionsApi\ConversionsApiServiceProvider" --tag="config"

The config file will be published as config/conversions-api.php with the following content:

return [
    /**
     * The access token used by the Conversions API.
     */
    'access_token' => env('CONVERSIONS_API_ACCESS_TOKEN'),

    /**
     * The pixel ID used by the Conversions API.
     */
    'pixel_id' => env('CONVERSIONS_API_PIXEL_ID'),

    /**
     * The Conversions API comes with a nice way to test your events.
     * You may use this config variable to set your test code.
     */
    'test_code' => null,
];

Conversions API

This package allows you to set the user data and events that will be sent to the Conversions API.

use Esign\ConversionsApi\Facades\ConversionsApi;
use FacebookAds\Object\ServerSide\UserData;
use FacebookAds\Object\ServerSide\Event;

ConversionsApi::setUserData(
    (new UserData())->setFirstName('John')->setLastName('Doe')
);
ConversionsApi::setEvent(
    (new Event())->setEventName('PageView')->setEventId('abc')
);

To actually send the data you must call the execute method.

use Esign\ConversionsApi\Facades\ConversionsApi;

ConversionsApi::execute();

This package also comes with a nice helper to send PageView events. By including the @conversionsApiPageView directive on a page, an event with the minimum required data (ip address, user agent and request url) will be sent to the Conversions API:

@conversionsApiPageView

Facebook Pixel

To deduplicate browser and server events this package will automatically generate a unique event ID for every request. This event ID should be passed along with your Facebook Pixel. This package comes with a few ways to do this:

Facebook Pixel

In case you want to directly load the Facebook Pixel script you may use the @conversionsApiFacebookPixelScript directive or directly include it.

@conversionsApiFacebookPixelScript
@include('conversions-api::facebook-pixel-script')

Google Tag Manager

A convenient dataLayer helper is included in case you want to load the Facebook Pixel through Google Tag Manager. By default a variable name conversionsApiEventId will be used:

@conversionsApiDataLayer
@include('conversions-api::data-layer')

You may also pass a custom variable name:

@conversionsApiDataLayer('yourDataLayerVariableName')
@include('conversions-api::data-layer', ['dataLayerVariableName' => 'yourDataLayerVariableName'])

Configuring Google Tag Manager

First off, you should add a new Data Layer Variable to your Google Tag Manager workspace. 1

Next up you should use the variable name that was passed along to the data layer view. 2

After saving the variable you should be able to use it in your Facebook Pixel script using the double bracket syntax: {{ Name of your variable }}. 3

Manually retrieving the event ID

In case you want to use another strategy to deduplicate your events you can do so by manually retrieving the event ID:

use Esign\ConversionsApi\Facades\ConversionsApi;

ConversionsApi::getEventId();

Testing

composer test

License

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