Reference

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

Message Passing Protocol

Summary

Message From Popup → Response from Native Plugin

“get dia settings” → “dia settings”
“set merchant settings” → “ack set merchant settings”
“set pixel” → “ack set pixel”
“reset” → “ack reset”
“gen feed” → “ack gen feed” (Feed approach only)
“set catalog” → “ack set catalog” (API approach only)
“set page access token” → “ack set page access token” (API approach only)

Important: The messages sent to and received from the popup all have the following JS object form:

{
  "type": "message name",
  "params": {...}
}

Client

string  type : “get dia settings”   
object  params : {}

Server Response

Sample response (Extra fields not documented below are ignored)

type : “dia settings”
params : 
{
  "clientSetup": {
    "developerMode"   // Set to true to receive helpful messages when debugging.
                      // Don't forget to remove it before launch, however.
    "popupOrigin"     // Launch Screen window URL
    "platform"        // Make sure this matches the platform 
                      // name string agreed on with Facebook.
    "predefinedPageId"  // Optional: Id of page that will force the selector 
                        // in the popup to be disabled and only show this page.
    "pixel" : { 
      "pixelId"       // Optional : if your platform already has a plugin
                      // to install the pixel. You may pass the id of the
                      // installed pixel here.
                      // The onboarding flow will auto-select this pixel
      "advanced_matching_supported" 
                      // Does your plugin support the advanced matching
                      // mentioned in the pixel section: true or false
    }
    "diaSettingId"    // Should be specified for returning users that have
                      // finished setup. This should be the same id sent by
                      // 'set merchant setting 
    "tokenExpired"    // Optional : Set this param to true if you detect
                      // that the API token has become invalid. The popup will 
                      // provide a way to generate a new token and send it 
                      // via message passing. [Example](https://github.com/facebookincubator/facebook-for-woocommerce/blob/508977217becf90d649abd7f7fb30446a69409ce/facebook-commerce.php#L610)
    "store": {
      "baseUrl"       // Public-facing URL of the user's store.
      "baseCurrency"  // Currency code e.g: USD
      "canSetupShop"  // Set to true to enable users to auto-create a fb shop
                      // and sync their products to it as part of setup.
      "timezoneId"    // See the [Timezone IDs](https://developers.facebook.com/docs/marketing-api/reference/ad-account/timezone-ids/v2.8)
      "storeName"     // Name of the user's store.
      "version"         // Platform Version.
      "plugin_version"  // Version of the native plugin.
      "php_version"     // Version of PHP (If Applicable)
    },
    "feed": {
      "enabled"          // Not required for API approach.
      "format"           // Not required for API approach.
      "totalVisibleProducts" // An int representing the number of 
                             // products in the store.
    },
    "feedPrepared": {
      "feedUrl"          // Not required for API approach.
      "feedPingUrl"      // Optional : A URL which will be accessed prior
                         // to feed generation.
                         // it should return a time in seconds to wait 
                         // while the feed is generated in the background.
      "samples": [       // Sample product information.
                         // This format should be an array of 12 objects.
       12 x 
          {
            "id": 
            "title": 
            "description": 
            "link": 
            "image_link":    // Providing this is critical for the
                             // onboarding flow popup to have product
                             // images render in the background.
            "brand": 
            "condition": 
            "availability": 
            "price":
          },
       ]
  }
}

Supported Parameters — Message Passing Protocol

Supported Parameters — dia settings > clientSetup

Parameter Description

developerMode

Set to true to receive helpful messages when debugging. Remove before launch.

popupOrigin

Launch screen window URL.

platform

Should match the platform name string agreed with Facebook.

predefinedPageId

Optional. Page ID that forces the selector in the popup to be disabled and only display this page. pixel

Supported Parameters — dia settings > pixel

Parameter Description

pixel_id

Optional, if your platform has a plugin to install the pixel. You can pass the ID of the installed pixel here. The onboarding flow will auto-select this pixel.

advanced_matching_supported

Whether your plugin supports advanced matching in the pixel section. If yes, set to true; if no, set to false.

diaSettingId

Should be specified for returning users who have completed their setup. Should be the same ID sent by set_merchant_setting.

tokenExpired

Optional. Set this parameter to true if you detect that the API token has become invalid.

Supported Parameters — dia settings > store

Parameter Description

baseUrl

Public-facing URL of the user’s store.

baseCurrency

Currency code. Example: USD

canSetupShop

Set to true to enable users to auto-create a Facebook shop and sync their products as part of their setup.

timezoneId

See Timezone IDs.

storeName

Name of the user’s store.

version

Platform version.

plugin_version

Version of the native plugin.

php_version

Version of PHP, if applicable.

Supported Parameters — dia settings > feed

Parameter Description

totalVisibleProducts

An integer representing the number of products in the store.

Supported Parameters — dia settings > feedPrepared

Parameter Description

feedPingUrl

Optional. A URL accessed prior to feed generation. Should return a time, in seconds, to wait while the feed is generated in the background.

samples

Sample product information. Format should be an array of 12 objects.

Supported Parameters — dia settings > 12 x

Parameter Description

id

Required for dynamic ads and commerce.

Max character limit: 100

Unique ID for item. Can be a variant for a product. If you can, use the product's existing SKU. If there are multiple instances of the same ID, we ignore all instances. This maps to retailer_id after the product is imported.

Example: FB_product_0001

title

Required for dynamic ads and commerce.

Max character limit: 100

Name that's relevant and specific to each item. Include keywords and variants, such as brand names, item areas, attributes, or condition. Example: Blue Facebook T-Shirt (Unisex)

description

Required for dynamic ads and commerce.

Max character limit: 5000

Short text describing item. Don't include promotional text or any links. Use plain text (without HTML tags) for this field. Don't enter text in all capital letters. Use line breaks or italics to format your description. For commerce - To support HTML, use rich_text_description.

Example: A vibrant crewneck for all shapes and sizes. Made from 100% cotton.

link

Required for dynamic ads and commerce.

Max character limit: 5000

URL link to merchant's site (website landing page) where you can purchase or learn more about the item. Provide a graceful fallback if you don't have a URL (example: a link to the merchant's Facebook page).

Example: https://www.fb.com/t_shirt

image_link

Required for dynamic ads and commerce. Critical for the onboarding flow popup to render images in the background.

Max character limit: 5000

URL link to item image used in the ad. Provide proper image sizes.

For square (1:1) aspect ratios in the carousel ad format - Image should be 600x600. For single-image, dynamic ads - The minimum image resolution requirement is 1200x630. The minimum aspect ratio requirement is 4:5 and the maximum aspect ratio requirement is 1:91:1. If the image is outside this aspect ratio, Facebook crops it to be closest to either the minimum aspect ratio or the maximum aspect ratio, depending on its original aspect ratio.

For carousel image, dynamic ads - The minimum image resolution requirement is 500px x 00px, and Facebook crops it to a 1:1 aspect ratio.

Example: https://www.fb.com/t_shirt_1.jpg

brand

Required for dynamic ads and commerce. Critical for the onboarding flow popup to render images in the background.

URL link to merchant's site (website landing page) where you can purchase or learn more about the item. Provide a graceful fallback if you don't have a URL (example: a link to the merchant's Facebook page).

Example: https://www.fb.com/t_shirt

condition

Required for dynamic ads and commerce.

Item's current condition in your store: new, refurbished, used. Must be written in U.S. English. You must provide one of the values in this field; it can’t be left empty. Marketplace B2C products should mostly be new.

Example: new

availability

Required for dynamic ads and commerce.

Item's current availability in your store. Must be written in U.S. English. You must provide one of the following values in this field; it can’t be left empty. If item is in stock, use one of these accepted values:

  • in stock - Item ships immediately
  • available for order - Ships in 1-2 weeks
  • preorder - Available in future
  • out of stock - Not available in current stock
  • discontinued - Discontinued

Example: in stock

price

Required for dynamic ads and commerce.

Price of the item. Format price as the cost, followed by the 3-digit ISO currency code, with a space between cost and currency.

Example: 9.99 USD, 25.00 EUR

Supported Parameters — set merchant settings

Parameter Description

setting_ID

Unique ID representing the merchants onboarding settings.

Supported Parameters — set pixel

Parameter Description

pixel_ID

The pixel ID that the merchant chooses to share with your platform.

pixel_use_pii

Values are true | `false. This value tells us if the pixel uses personal identifiable information (PII).

Supported Parameters — reset

Parameter Description

See Description

There is no supported parameter for reset. This message is from the FBE popup asking your platform to delete all stored configurations + settings.

Supported Parameters — gen feed

Parameter Description

See Description

If you are using a feed approach, then this message prompts your platform to regenerate the feed.