Ads Plugin

Facebook Ads Plugin allows you to install and manage the Facebook Business Extension (FBE), create Facebook ads, and view ads insights on websites you manage.

If you already have an FBE entry point implemented, setting the configuration the same as the existing FBE entry point will allow the Ads Plugin to detect that FBE has been installed, and users will be able to see the Create Ad button without going through the FBE flow again.

Facebook Business Extension (v2) Ads Plugin is currently only available to approved partners. If you are interested in becoming a partner, please contact your Facebook representative for access. FBE requires the manage_business_extension capability.

If you do not have a representative, please fill out this form if you are an eCommerce partner or this form (available on desktop only) if you are in the Services vertical.

Before You Start

You will need:

  • The Facebook App ID that you have shared with your Facebook Partner for access to FBE. You can find the App ID in the Apps panel header at developers.facebook.com/apps or by clicking the My Apps link in the header that appears on all developers.facebook.com sub-pages.
  • Install the Facebook JavaScript SDK. You may copy and place the Basic Setup code snippet on the website page to install Ads Plugin.

Add the Plugin

Ads Creation

The Ads Creation plugin takes the merchant through FBE installation if FBE is not already set up for the business (verifies if FBE is installed for the external business id) and shows the Create Ad button to the Facebook lightweight ad interface when FBE is installed.

Add the following code on the webpage with appropriate values for the Ads Creation widget to appear. See Reference for field descriptions.

Formatted for readability.
<div class="fb-lwi-ads-creation" 
       data-fbe-extras="<extras-for-fbe-configuration>"
         data-fbe-scopes="<permission-scopes>"
         data-fbe-redirect-uri="<url-to-be-redirected-to-when-popup-closes>"
></div>

Ads Insights

Ads Insights plugin takes the merchant through FBE installation if FBE is not already set up for the business (verifies if FBE is installed for the external business id) and shows ads performance such as reach, purchases and spending.

Add the following code on the webpage with appropriate values for the Ads Creation widget to appear. See Reference for field descriptions.

Formatted for readability.
<div class="fb-lwi-ads-insights" 
       data-fbe-extras="<extras-for-fbe-configuration>"
         data-fbe-scopes="<permission-scopes>" 
         data-fbe-redirect-uri="<url-to-be-redirected-to-when-popup-closes>" 
></div>

Reference

FieldTypeDescription

data-fbe-extras

Required

string

Define Facebook Business Extension-specific flows, such as the features and settings used to configure for the seller. business_config, setup, and repeat are required. See the FBE Reference for more options.

data-fbe-redirect-uri

Required

string

URI to be redirected to when the pop-up closes after FBE install. The redirect url will have the code and state params. The code can be exchanged for an access token. If Webhook is implemented, you will receive the access token through a Webhook FBE install event.

data-fbe-scope

Required

string

manage_business_extension is required in the scopes. Optionally, include appropriate scopes for FBE installation such as catalog_management, ads_management, business_management. These permission scopes have to be requested for your app from the App Dashboard via App Review.

data-fbe-state

Optional

string

A string value created by your app to maintain state between the request and callback. This parameter should be used for preventing Cross-site request forgery and will be passed back to you, unchanged, in your redirect URI.

data-hide-manage-button

Optional

boolean

For Ads Creation settings only. Setting to true hides the FBE manage button on Ads Creation widget.

Localization

You can change the language of the embedded comments plugin by loading a localized version of the Facebook JavaScript SDK. When you load the SDK, change the value of src to use your locale. Replace en_US with your locale, for example fr_FR for French (France):

src="https://connect.facebook.net/fr_FR/sdk.js#xfbml=1&version={latest-api-version}"

You may need to adjust the width of a Social Plugin to accommodate different languages.

Quick Test - Sample Code

<body>
    <script>
        window.fbAsyncInit = function () {
            FB.init({
                appId: "your-app-id",
                autoLogAppEvents: true,
                xfbml: true,
                version: "v11.0",
            });
        };
    </script>

    <script async defer crossorigin="anonymous" src="https://connect.facebook.net/en_US/sdk.js"></script>

    <h3>Ads Creation</h3>

    <div
        class="fb-lwi-ads-creation"
        data-fbe-extras="{'business_config':{'business':{'name':'Sample Business'}},
      'setup':{'external_business_id':'my-sample-business',
      'timezone':'America/Los_Angeles',
      'currency':'USD',
      'business_vertical':'ECOMMERCE'},
      'repeat':false}"
        data-fbe-scopes="manage_business_extension,ads_management"
        data-fbe-redirect-uri="https://samplebusiness.commerceapp.com/marketing/fb"
    ></div>

    <h3>Ads Insights</h3>

    <div
        class="fb-lwi-ads-insights"
        data-fbe-extras="{'business_config':{'business':{'name':'Sample Business'}},
      'setup':{'external_business_id':'my-sample-business',
      'timezone':'America/Los_Angeles',
      'currency':'USD',
      'business_vertical':'ECOMMERCE'},
      'repeat':false}"
        data-fbe-scopes="manage_business_extension,ads_management"
        data-fbe-redirect-uri="https://samplebusiness.commerceapp.com/marketing/fb"
    ></div>
</body>

Be sure to replace your-app-id with an actual app id value for the sample code to work on your webpage. After the quick test, replace all fields with the appropriate values.