Download the PHP package setono/meta-conversions-api-bundle without Composer

Meta / Facebook Conversions API bundle

Work with the Meta / Facebook Conversions API in your Symfony application. Under the hood this bundle integrates the Meta Conversions API PHP SDK library.

Requirements

• PHP 8.1+
• Symfony 6.4 or 7.4
• A PSR-18 HTTP client and PSR-17 factories (see Installation)

Installation

The SDK sends events through a PSR-18 client and PSR-17 factories, which it discovers automatically. If your application does not already ship both, install them alongside the bundle:

The SDK depends on php-http/discovery, which contains a Composer plugin. Composer asks whether to allow it, and either answer works. To skip the prompt (e.g. in CI) declare it in your composer.json:

Installing the bundle also installs the Bot Detection Bundle, which is used to filter bot requests.

If you want to handle consent (i.e. cookie/GDPR consent), install the consent bundle and enable the consent option (see Configuration):

Upgrading from 0.1.x? See UPGRADE.md.

Configuration

All options with their defaults:

Route the command to a transport

Server side events are dispatched on your application's default Messenger bus. The bundle does not register a bus of its own, so your bus configuration is left untouched. Point the bundle at another bus with the server_side.message_bus option if you prefer.

Route the command to an async transport. Without it, Messenger handles the command synchronously, which means the http call to Meta happens inside the visitor's request: their page waits for Meta's round trip, and Meta's availability becomes your availability.

With a transport, Messenger also retries a failed send and moves it to the failure transport when it keeps failing.

Either way, a send that fails is logged as an error and never propagates into the response, so an expired access token or an outage at Meta cannot break the page.

Usage

How it works

Dispatching a ConversionsApiEventRaised runs the event through a pipeline of listeners. The bundle populates the event first, then leaves a gap for your own listeners, then filters and sends:

Two things follow from this:

• Enrich at PRIORITY_ENRICH, which is the default priority of any listener. Everything the bundle knows about the request is populated by then, and traffic the bundle does not want to track has already been discarded, so your listeners never do work for a bot.
• A listener below PRIORITY_ENRICH may never run, because propagation can already have been stopped.

The constants live on ConversionsApiEventRaised, so you can position your listener without hard coding a number.

Enriching an event

Everything the Conversions API can do beyond the browser pixel comes from the user data you attach server side. Meta normalises and hashes it for you, so set the raw values:

You can also replace a step instead of adding to it: alias PixelProviderInterface, FbpContextInterface or FbcContextInterface to your own service, or register a listener above the corresponding populate priority.

Why did my event not show up?

Every listener that drops an event says so at debug level on the setono_meta_conversions_api Monolog channel: the bot filter, the user agent filters, the no-pixels check, and each of the three consent gates. The send handler logs a warning when a pixel has no access token.

Events that are not raised in a browser request

The pipeline assumes the event belongs to the request being handled. PopulateRequestPropertiesSubscriber therefore fills in the source url, client ip and user agent of the current request, and the bot and user agent filters only apply to events whose actionSource is website (the default).

For an event raised from a console command, a message handler or an incoming webhook, set another action source so the filters leave it alone:

If such an event is raised while handling an HTTP request, for instance a webhook from your payment provider, the request properties still describe that request, not the customer. Overwrite them in a listener above PRIORITY_POPULATE when they matter.

Giving Meta its own timeout

Because the client is a normal service, a scoped client works out of the box:

Note that a scoped client is a Symfony HttpClientInterface, so wrap it for PSR-18:

Graph API version

Events are posted to the Graph API version of the installed facebook/php-business-sdk package (the SDK reads ApiConfig::APIVersion): v26.0 with the 26.x package, v25.0 with 25.x. To move to a newer Graph API version simply run composer update facebook/php-business-sdk.

Test the integration

Take the test event code from Meta / Facebook's event manager and append it to any url on your website: https://example.com/?_testEventCode=[YOUR TEST EVENT CODE] (or ?_test_event_code=[YOUR TEST EVENT CODE]). The code is saved in the session, so all your subsequent requests are sent with it. Clear it again with an empty value: https://example.com/?_testEventCode=.

Because anyone who can add a query parameter would otherwise be able to divert their own conversions into the test bucket, the query parameter is only honoured when test_event_code.query_parameter is enabled. It follows kernel.debug by default, so it works in dev and is off in prod. To send every event as a test event, for instance from a staging environment, set test_event_code.value instead.