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

Meta (Facebook) Conversions API PHP SDK

[!NOTE] This is the documentation for 2.x, which is in beta. The stable release lives on the 1.x branch. If you are upgrading, see UPGRADE-2.0.md.

A small, typed PHP library for sending server-side events to Meta's (Facebook's) Conversions API, and for generating the matching browser-side fbq() snippets.

It gives you plain, well-typed objects (Event, User, Custom, …) and takes care of the fiddly parts for you:

• Automatic normalization & hashing of customer information — you pass raw emails, phone numbers, names, etc. and the SDK normalizes and SHA-256 hashes them the way Meta requires. Never hash this data yourself.
• Server + browser deduplication — every event gets an eventId you can reuse on both sides so Meta counts it once.
• Bring your own HTTP client — built on PSR-18/PSR-17 with auto-discovery, so it works with any compliant client.

Requirements

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

Installation

The SDK talks to the API through a PSR-18 client and PSR-17 factories, which it discovers automatically. The simplest way is to install it together with an implementation:

2.0 is in beta. Until it is stable, ask for it explicitly, e.g. composer require setono/meta-conversions-api-php-sdk:^2.0@beta.

symfony/http-client works just as well if you prefer it:

If your project already ships a PSR-18 client and PSR-17 factories you only need the SDK itself (composer require setono/meta-conversions-api-php-sdk); see Using your own HTTP client.

Quick start

An Event is created with a random eventId and the current eventTime already set, and defaults to the website action source. Pass a different source as the second constructor argument if needed (e.g. new Event(Event::EVENT_PURCHASE, Event::ACTION_SOURCE_PHYSICAL_STORE)).

Sending a richer event

Event::$customData holds the event-specific data (value, currency, contents, …) and Event::$userData holds the customer-matching data:

Multiple pixels

Add more than one Pixel and the event is sent to each of them (every pixel carries its own access token):

Test events

While integrating, set a test event code so the event shows up in the Test events tool in Events Manager instead of counting as real traffic:

Error handling

Everything the SDK throws implements Setono\MetaConversionsApi\Exception\ExceptionInterface, so you can catch it all in one place. There are three concrete exceptions, one for each thing you can do about a failure:

ResponseException::$errorResponse is the error Meta reported, with its message, code, subcode, type, traceId, the transient flag and the user-facing texts. It is null when the body is not in Meta's error format, which typically means the response came from a proxy. The raw body is always available as $e->body.

InvalidArgumentException extends PHP's own \InvalidArgumentException, so a plain catch (\InvalidArgumentException $e) works too.

Sending events later, e.g. through a queue

User holds the raw email addresses, phone numbers and names until the payload is built, so an Event should not be queued as is. Event::prepare() returns a PreparedEvent instead: the payload, already normalized and hashed, together with the pixels and the test event code. It is made of scalars, arrays and Pixel objects only, so it serializes with the PHP serializer or the Symfony serializer without any tricks. Hash at capture time, send later:

withoutAccessTokens() keeps the access tokens out of the queue and of any failure storage behind it, and withAccessTokens() takes the tokens indexed by pixel id and leaves pixels that are not in the list as they are. Both return a new instance. If your queue is trusted with the access tokens, you can skip both calls.

Pixels that still have no access token when you send are skipped, and the client logs an error that names them. A pixel that is only used in the browser therefore does not keep the other pixels from receiving the event. If none of the pixels has an access token, which is what happens when withAccessTokens() is forgotten, the client throws an InvalidArgumentException before any request is made.

Browser-side tracking with deduplication

To get the best match quality Meta recommends sending events both server-side (this SDK) and from the browser, using the same eventId so they are deduplicated. FbqGenerator produces the matching JavaScript:

Both methods wrap the output in a <script> tag by default; pass false as the last argument to get the raw JavaScript instead (e.g. to combine several calls into one tag). Because their output goes straight into a page, they do not throw when the data cannot be encoded as JSON: they log an error and return an empty string.

Custom events

Any event name that isn't one of the standard Event::EVENT_* constants is treated as a custom event. FbqGenerator will emit trackCustom instead of track for these:

fbc / fbp cookies

The _fbc and _fbp cookies improve attribution. Assign them to the user data either as raw strings or as the typed value objects, which validate the format:

fromString() throws an InvalidArgumentException if the value does not have the expected format.

Using your own HTTP client

By default the client auto-discovers a PSR-18 client and PSR-17 factories. To inject your own (e.g. a preconfigured Guzzle client with timeouts and retries), use the setters:

Logging

Client is LoggerAware. Pass any PSR-3 logger and the SDK will, for example, warn you when you try to send an event that has no pixels associated, or when it skips a pixel because it has no access token:

Extending events

Event is intentionally not final, so you can build domain-specific events with sensible defaults:

Development

License

This library is released under the MIT License.