Best Practices

The Facebook Business Extension, v1 is currently only available to whitelisted Partners. Please contact your Facebook representative for access.

This guide describes the best practices we recommend to use for Facebook Business Extension, v1.

Before You Begin

  • Be aware of XSS vulnerabilities while building your plugin. For example, if using PHP, use esc_js, strip_tags and html_entity_decode to sanitize inputs. The query string provided to the pixel Search event is one area of concern.

  • We encourage you to make use of the sample code provided in the document and adapt it to your plugin.

Pixel Installation

  • Add the version for the platform and plugin in pixel fires. For example, {'agent': 'exopencart-2.3.0.2-1.0.0.'} is for OpenCart, where platform is 2.3.0.2 and plugin is 1.0.0.
fbq('init', '<pixel_id>', {<pii_data>}, {'agent':'pl<platform_name>'});
  • If possible, you should include advanced pixel matching in pixel fires.
  • Use the Chrome Facebook Pixel Helper tool to verify that your pixel implementation is working.
  • Choose the right type of pixel event fields for standard events. For example, choose product_group when a user is seeing a product, but you don't know all the details of the product. For example, when there's a t-shirt model, but the red and blue ones have a different product_id.

    • If the user didn't select a color, you could fire the ViewContent event with product_group and their product_group_id instead of product_id.
    • It's not always possible to implement this correctly; for example, if there are no hooks for the user selecting a specific color.
  • Use AddToCart carefully

    • Due to technical constraints, some platforms fire this event when someone first views their cart with a new item. If possible this event should fire when the product is added to the cart.
    • One option is to fire this event multiple times: when someone adds a product to cart and also when someone sees the full cart. There are fewer downsides and it simplifies your work.

Learn more about how to install the Facebook pixel.

Feed Approach

  • Feed format—Your feed format should follow the guidelines described in Catalog, Get Started, Marketing API, or Use a Data Feed Template, Help Center.
  • Make feed file externally accessible—If Facebook cannot access the feed file, the products cannot get uploaded to Facebook.
  • (Optional) Replicate the feed file your plugin generates across all servers that support a given store. For example, your website is www.yourstore.com and someone creates a fbfeedfile.tsv feed file. If you don't replicate data across all machines, when we try to find www.yourstore.com/fbfeedfile.tsv, it can reach a server without the file, resulting in failure. You can solve this by storing the feed file in a directory that, in the case of multiple host machines, is shared or synced across all machines.
  • Test accordingly—The feed generation logic may take a long time when there are a lot of products. Make sure you account for this and test accordingly, ensuring that your feed generation mechanism does not time out.
  • Make the directory writable—You should check this before writing the feed file for the first time. If a permission error occurs when writing the feed, your plugin should handle this smoothly and notify the user to change their permissions before using the plugin.

API Approach

  • Unlike the Feed Approach, you need to explicitly handle product deletion via an API call.
  • The Facebook API follows versioning patterns, depending on the API used. You may need to update your plugin to keep up with changes in the Facebook API.
  • Your plugin should handle the case where the API token becomes invalid, and notify the user.
    • The validity of the token can be checked by trying an API call; for example, to get the Page name.
    • The Onboarding Flow popup provides a mechanism to reset the API token, if you specify tokenExpired.
    • An API token can become invalid if the user deletes the underlying page, resets their Facebook password, deletes their Facebook account, and so on.
  • Without batching, stores with many product updates could use a lot of bandwidth communicating with Facebook.

Launch Screen

  • Close existing popups—When opening the popup, check for and close any existing Facebook Onboarding Flow popup. Optionally, when the landing page UI is closed or refreshed, close any open Facebook Onboarding Flow popups.

  • Change the button name—If using a button to launch the popup, change the button name after you have completed the Facebook Onboarding Flow popup once and have received the set merchant settings message. Note For this language, we recommend "Get Started" and "Manage Settings". See example - fae.js.

  • (Optional) Add link and text for ad creation and Settings button—Change the UI after you have completed your setup to include the Create Ad and Settings buttons with a link to our ads interfaces and the text, as follows:

    • The Create Ad button should point to https://www.facebook.com/ads/dia/redirect/?settings_id=merchant_settings_id that takes you to Ads Manager.
    • For public example code, see example - facebook-commerce.php or example - fae.js.
    • In this case, the Settings button opens the popup.

    • The Facebook popup can render a custom version of the Facebook Onboarding Flow that we refer to as the control panel. Learn more about this in Message Passing

    • Depending on your parameters you pass to the FBE popup, the steps in the popup will be different. It's important to choose the correct settings.

Message Passing

  • Use existing sample code—We encourage you to make use of the sample code provided in the document and adapt it to your plugin.
  • Set developerMode param to true—We strongly recommend setting the developerMode param to true in the initial dia settings message. In this mode, the popup validates the message structure you send for potential errors and displays a warning if any issues are found.

  • Report uncertainty of bug—If you're absolutely certain this is not a bug in your message passing, contact your Facebook representative with as much information as possible. This the most common issue encountered by plugin developers and is almost always caused by incorrect implementation of message passing or malformed messages.

  • Pass a Platform name —In the platform field of the dia settings response message, pass your Facebook-assigned platform name (this is case-sensitive). If you don't have one, contact your Facebook representative.

  • Verify if fields are not blank—When specifying the necessary data for the dia settings message, verify if the fields are not blank in all cases. We recommend adding fallback behavior. For example, if the store name is blank, use the store url in that field, or if the description is missing, use the title.

  • Be aware of XSS vulnerabilities while building your plugin. For example, if using PHP, use esc_js, strip_tags, and html_entity_decode to sanitize inputs.