Ads Plugin

    Ads Plugin

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

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

    Before You Start

    You will need:

    • The Meta App ID that you have shared with your Meta Partner for access to Meta Business Extension. 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 Plugins

    Ads Creation Plugin

    The Ads Creation plugin takes the merchant through Meta Business Extension installation if Meta Business Extension is not already set up for the business (verifies if Meta Business Extension is installed for the external business id) and shows the Create Ad button to the Facebook lightweight ad interface when Meta Business Extension 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 Plugin

    Ads Insights plugin takes the merchant through Meta Business Extension installation if Meta Business Extension is not already set up for the business (verifies if Meta Business Extension 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>

    Field Reference

    FieldDescription

    data-fbe-extras

    Type: string

    		Required.

    Defines Meta 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 Meta Business Extension Reference for more options.

    data-fbe-redirect-uri

    Type: string

    		Required.

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

    data-fbe-scope

    Type: string

    		Required.

    The manage_business_extension is required in the scopes. This is a private permission that your Meta representative will need to add your app to the allowlist for, and cannot be requested through App Review.

    Optionally, include appropriate scopes for Meta Business Extension installation such as catalog_management, ads_management, business_management. These permission scopes must be requested for your app from the App Dashboard via App Review.

    data-fbe-state

    Type: string

    		Optional.

    A string value created by your app to maintain the 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-preferred-ad-options

    Type: string

    		Optional.

    Partners can configure which ad objectives to surface in the ad creation plugin by inputting upto 4 objectives in a comma separated string in the order of preference. User eligibility for the objective will be checked and users will be shown at most 3 eligible objectives in the preference order.

    Supported options are: MESSAGES, WEBSITE_PURCHASES, CATALOG_SALES, WEBSITE_VISITS, PAGELIKES.

    Default value is: MESSAGES, WEBSITE_PURCHASES, CATALOG_SALES, WEBSITE_VISITS

    data-hide-explore-more-options

    Type: boolean

    		Optional.

    True hides the explore more options on the ad creation plugin. When the value is true, if the user is not eligible for any of the configured options, a Create ad button will be shown instead.

    data-lazy

    Type: boolean

    		Optional.

    True means use the browser's lazy-loading mechanism by setting the loading="lazy" iframe attribute. The effect is that the browser does not render the plugin if it's not close to the viewport and might never be seen. Value can be true or false (default).

    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>

    With Objective Customization

    <body>

<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-preferred-ad-options='MESSAGES, CATALOG_SALES, WEBSITE_VISITS'
        data-fbe-scopes="manage_business_extension,ads_management"
        data-hide-explore-more-options=false
        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.

    Learn More