Download the PHP package esign/laravel-conversions-api without Composer

Interact with the Facebook Conversions API

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

Installation

You can install the package via composer:

Next up, you can publish the configuration file:

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

In case you want to customize the view components you may also publish the views:

Conversions API

Events

To add events to the conversions API you may use the addEvent, addEvents or setEvents methods. Retrieving or clearing events may be done using the getEvents and clearEvents methods:

Adding events won't cause them to be sent to the Conversions API. To actually send the events you must call the sendEvents method:

Creating event classes

To make things a bit cleaner you may extend Facebook's default event class:

User Data

This package also comes with a way to define default user data for the user of the current request. You may do so by calling the setUserData method. You can set the user data for every incoming request by creating a custom middleware like this one:

You can now use it in App\Http\Kernel as a global middleware or a route middleware.

You may now pass the user data along with your events:

Event deduplication

This package comes with a few ways to assist you in deduplicating browser and server events. This can either be done using the Facebook Pixel directly or through Google Tag Manager's data layer.

Facebook Pixel

Before attempting to send events through Facebook Pixel make sure to load the pixel script:

This will render the following html:

This package will attempt to provide as much advanced matching data as possible by using user data from the ConversionsApi. For example when an email address is set, it will automatically be provided to the init method:

Now that your Pixel is correctly initialized, it's time to send some events. Sadly the parameters between the Conversions API and Facebook Pixel are not identical, so they must be mapped to the correct format. An easy way of doing this is by extending the FacebookAds\Object\ServerSide\Event class and implementing the Esign\ConversionsApi\Contracts\MapsToFacebookPixel interface on it:

You may now pass any class that implements the MapsToFacebookPixel interface to the view component responsible for tracking Facebook Pixel events:

This will render the following script tag:

To retrieve a list of all events that implement the MapsToFacebookPixel interface you may call the filterFacebookPixelEvents method:

In case you want more control over what's being rendered, you may always use the anonymous component:

Google Tag Manager

Before attempting to deduplicate events through GTM make sure to configure your GTM container id and include the necessary scripts:

This package comes with a view component that will map all user data from the ConversionsApi to dataLayer variables:

For example when an email address is set, it will be automatically mapped to a dataLayer variable. Check the source of the view component to see a list of all possible variables.

Now that your Pixel through GTM is correctly initialized, it's time to send some events. An easy way of doing this is by extending the FacebookAds\Object\ServerSide\Event class and implementing the Esign\ConversionsApi\Contracts\MapsToDataLayer interface on it:

You may now pass any class that implements the MapsToDataLayer interface to the view component responsible for tracking Facebook Pixel events:

This will render the following script tag:

To retrieve a list of all events that implement the MapsToDataLayer interface you may call the filterDataLayerEvents method:

In case you want more control over what's being rendered, you may always use the anonymous component:

PageView Events

This package ships with some helpers to track PageView events out of the box. These helpers will automatically send both Conversions API & Facebook Pixel events and provide event deduplication.

Note Make sure to always include these view components after you've already looped over any other events currently defined on the ConversionsApi. Including these view components will clear any existing events.

In case you're using the Facebook Pixel directly:

Or by using Google Tag Manager. The data-layer variable to deduplicate events is called conversionsApiPageViewEventId.

Troubleshooting

PageView events are not shown as deduplicated in the test events dashboard

Event deduplication for PageView events should be fine out of the box, since the event name and event id parameters have been provided. However, when serving your application locally the ip address returned by Laravel's request()->ip() will be 127.0.0.1. This is different from the ip address sent through Facebook Pixel, causing the Conversions API and Facebook Pixel events to not be deduplicated. This issue should solve itself once the application will be ran in production.

Whitelisting Cookies in Laravel

When using \App\Http\Middleware\EncryptCookies::class in \App\Http\Kernel::class, ensure to whitelist _fbp and _fbc cookies to prevent null values in loading DefaultUserData::create(). Update the $except property in the EncryptCookies middleware as shown below:

Testing

License

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