Meta Pixel

The Meta add-on brings everything Meta to Analytics Core: the Pixel and its browser event handler, the Conversions API server route, the wait for the Pixel's first cookie, and the wording of its results. Core carries none of it. Both channels use Analytics → Settings → Meta, a page the add-on registers.

Configure Meta

1. Enter your Pixel ID for the browser integration.
2. Enter a Conversions API Access Token for server delivery to the same pixel.
3. Review the separate Send … from the browser and Send … server-side toggles. Event toggles default to enabled once the channel is configured.
4. Save, send a test event from Tools, and confirm the interaction in Meta Events Manager.

Disable Meta Analytics pauses Meta delivery. The access token stays on the server and is sent to Meta in the request body, keeping it out of the request URL.

What this add-on adds

• The Meta Pixel (fbevents.js) in the browser, revoked before init while marketing consent is denied and granted or revoked again on every consent change, plus the metaPixel event handler.
• The metaConversionsAPI server route, with a transport whose one job is to hold a server event until the Pixel has set its first-party cookie. It adds no event properties of its own: matching data comes from the cookies and headers on the request.
• The reserved custom-event names access_token, id, test_event_code and user_data, which would collide with its settings.
• The wording of Meta's error codes and diagnostic results, the Test Events code input on its Tools card, and the Events Manager links beside it.

Events and deduplication

page_view maps to PageView, search to Search, and a contact-link click to standard Contact. Contact records only the method (email, phone, or sms), without the address or phone number. Generic form submissions remain custom events; they do not automatically mean a lead or a completed registration. Scroll, clicks, downloads, sharing, audio and video map to corresponding custom Meta events. Their exact parameters come from the add-on's provider map.

When both Pixel and Conversions API carry the same captured event, they use the same event name and event ID. This supplies the pair Meta needs for browser/server deduplication. Do not create a second independently identified event for the same interaction in another integration.

Conversions API includes the page source and referrer URLs, available browser user agent, a validated public visitor IP, and available _fbp/_fbc identifiers. When a usable _fbc is absent, the add-on derives it only from a real fbclid in the event URL, using the event's observed capture time. This fallback does not create a persistent cookie or invent a click identifier. It excludes private and reserved IPs and does not trust arbitrary forwarding headers.

Only correctly shaped Meta cookies are forwarded. Malformed values are ignored; valid long click identifiers are preserved for matching. The API-version filter applies equally to live delivery and Tools → Send test event, so diagnostics exercise the same selected Graph API version.

On a first visit with marketing consent, a configured Pixel, and a selected server route, the add-on gives the Pixel up to one second to create its first-party cookie before the event is posted, checking every 50 milliseconds. Existing cookies skip this wait. Page exits release pending events immediately, a consent withdrawal releases them too, and navigation-related events do not wait. A blocked Pixel does not delay subsequent events after that deadline. Other add-ons' waits run at the same time rather than adding up.

Consent and identity

Meta uses the shared marketing category in Analytics Privacy. Pixel consent is revoked before initialization while marketing is denied, and server events are withheld. The browser library can still load; this is not a script-blocking consent manager. Global Privacy Control denies marketing by default.

Send hashed logged-in user data is off by default. The separate Identify signed-in users after consent setting allows a salted account identifier on the server route. These values come from the authenticated WordPress account rather than a visitor-provided event field.

Verification and failures

The optional Test Events code setting is used only by Tools → Send test event. The Tools card shows a Test Events code (optional) field prefilled from that setting and an Open Meta Test Events button for the configured dataset. Copy a code from Events Manager to inspect the synthetic xpac_test_event in its Test Events view, or clear the field to send one diagnostic event to the normal dataset. The field changes nothing you have saved, and ordinary visitor events never inherit it. On the command line the same code is wp xpac analytics test-event metaconversionsapi --test-event-code=<code>.

A successful diagnostic reads "Meta confirmed receiving 1 diagnostic event(s)." and adds notes saying where to look (Test Events with the code used, or the dataset's Overview, which Meta may take up to 30 minutes to update) and the Meta trace ID, with a View in Meta button for that view. Match those details in Events Manager. A successful synthetic test checks the connection; it does not measure real visitors' matching quality or prove ad attribution. For that, use a consented website interaction and inspect its matching information in Meta.

If a real event is rejected without any usable matching identifier, check that Pixel cookies are available after marketing consent and that your trusted proxy supplies the real public visitor IP. A private localhost address cannot supply that IP, and an ad blocker may prevent Pixel from creating cookies. Analytics reports the missing identifiers; it does not substitute fake visitor data. A rejected access token, a token without permission for the dataset and a rejected parameter each get their own sentence, and a diagnostic's notes carry Meta's error code and subcode so you can look them up in Events Manager.

Tools keeps the most recent server delivery failure. A valid Conversions API response reports accepted events; a transport or provider error does not trigger a durable retry. On a host without early response release, the default nonblocking request only confirms dispatch.

See the Analytics developer guide for trusted-proxy configuration and Meta hooks for request and API-version filters.