Meta/Facebook Pixel Event Tracking & Conversion API

Installation instructions, documentation and FAQs for the Shopware plugin

1. Installation and basic activation

  1. Upload the app in your Shopware administration under Extensions / Apps and install it.
  2. Go to the app's configuration.
  3. Add your required Facebook Pixel ID in the appropriate field.
  4. Activate the app.

2. Setting up the conversion access token (for the conversion API)

To use the Facebook Conversions API for more reliable, server-side tracking, you need an access token.

  1. Generate the Facebook Pixel Conversion Access Token. The most up-to-date and detailed instructions for generating the token can be found directly in the Facebook Developer Documentation: https://developers.facebook.com/docs/marketing-api/conversions-api/get-started/?locale=de_DE#use-your-own-app
  2. Copy the generated access token and paste it into the Conversion Access Token field in the plugin configuration.

3. Integration with your external cookie consent manager (expert mode)

Depending on which external Cookie Consent Manager (CCM) you use, the value of the **data attribute** must be configured correctly so that the Facebook pixel is only loaded after consent has been given.

  • If you leave the field blank, we use the default values:
    • For User CentricsThe default value is „Facebook Pixel“.
    • For Cookie BotThe default value is „marketing“.
  • For manual configuration (expert mode): Follow the specific instructions for your CCM to determine the correct value and enter it in the panel of experts one.

4. Provide opt-out link for Facebook Pixel

To give your users the option to specifically disable tracking by the Facebook Pixel (opt-out), our plugin supports a simple HTML code.

Embed the following HTML code on any page of your shop (e.g. in the Privacy policy):

<code><a onclick="javascript:fbqOptout();" >Disable Facebook Pixel Tracking for this website here</a>

After clicking on this link, tracking will be deactivated for the user.

5. own log file for the Facebook pixel plugin

If you want to have the plugin entries written to a separate, daily rotating log file, add the following file to your Shopware installation config/packages/monolog.yaml (create if not available) by the following block:

monologue:
    channels: ["biloba_ad_facebook_pixel"]
    handlers:
        biloba_ad_facebook_pixel:
            type: rotating_file
            path: "%kernel.logs_dir%/biloba_ad_facebook_pixel_%kernel.environment%.log"
            level: debug
            channels: ["biloba_ad_facebook_pixel"]
            max_files: 14

Subsequently bin/console cache:clear execute. The entries then end up in var/log/biloba_ad_facebook_pixel_prod-YYYY-MM-DD.log.

With level: debug both errors and the payloads of all successful API calls are recorded - regardless of whether they are sent synchronously or asynchronously. The plugin setting „Activate Facebook Pixel Conversion API Logging“ is therefore effectively superfluous and can remain „off“.

Only log via the plugin setting (without own log file)

If you don't want to create your own monologue handler, you can alternatively use the plugin config switch - with two restrictions:

  1. In the plugin settings „Deactivate “Send conversion API calls asynchronously via the Shopware message queue" (the toggle for logging only takes effect in the sync path).
  2. „Activate Facebook Pixel Conversion API logging“ switch on.
  3. In the Shopware main logger, set the level to at least info (see section „Log level in the main log“).

The payloads then end up in the general var/log/prod-*.log and must be grep can be filtered.

Filter entries from the main log file

Entries from the shared Shopware log file:

grep -a "biloba_ad_facebook_pixel" var/log/prod-$(date +%F).log > fb-pixel.log

Log level in the main log

So that in the general Shopware log, in addition to errors info- or debug-entries become visible in config/packages/prod/monolog.yaml the level of the main-handler accordingly (info for payloads, debug for success logs) and clear the cache. This is not necessary when using your own log file (see above).

FAQs

Yes, our plugin offers the option of using the Conversion API.

This can take up to 48 hours (please check whether the value is correct)

Extend the shopware.yaml, or better a z-shopware.yaml in the /config/packages folder (where the Admin Worker is also switched off):

    messenger:
        routing_overwrite:
'Biloba\AdFacebookPixel\Core\Messages\ConversionApiMessage': low_priority

This moves the conversion messages of the Facebook Pixel extension to the "low_priority queue" of the "messenger_messages" table of the database

No solution found?

Describe your problem to us - we'll take a look at it and get back to you as soon as possible.

Submit a support request