Integrate with the Popup via Message Passing

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

Your plugin's launch screen should support message passing between the browser and the popup.

Requirements

  • Internet Explorer—Message Passing does not work on Internet Explorer (IE). You should detect IE and display a message, Please use another browser. See Supported Parameters, dia settings for details.
  • Image rendering—If product images don't render on the product page, this indicates a problem with the formatting of the samples portion of the message. Samples should be an array of (up to) 12 x JSON objects. For details, see samples - 12 x and Appendix I.
  • Session timeout—If your launch screen is closed or the user's session cookie times out, message passing fails. The popup doesn't immediately detect breaks, but if someone tries to click Finish in the Facebook Onboarding Flow, it sends a set merchant settings message. If there's no response from the launch screen, the popup enters an error state, resulting in the user having to try the Facebook onboarding flow again.
  • Subdomain redirect—For a small subset of users, the subdomain for the Facebook Onboarding Flow popup may redirect to web.facebook.com, which can break message passing. If you encounter this case, be sure your plugin can handle it by changing the origin param sent to postMessage accordingly. See example to determine which plugin handles this case.

How it Works

Message passing is a method by which different browser windows communicate, and that communication occurs entirely on the browser. It's implemented entirely through JavaScript code; see requirements for Facebook Business Extension-compliant message passing below. Your implementation should support all described messages.

The image shows some of the messages sent between the popup and a correctly implemented plugin during the initial onboarding process.




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

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

Considerations for Message Passing

Include domain and subdomain of your communication window

The origin param passed to window.postMessage(...) by your plugin must contain, at a minimum, the domain and subdomain of the window you're communicating with. Otherwise, message passing won’t work.

Implement event listeners and response handlers

Your plugin should implement event listeners and response handlers for certain required messages: get dia settings, set merchant settings, set pixel. For details, see Supported Parameters.

There are 3 main message types:

  • get dia settings—When you get this message, the response must be structured information about the store. It should have at least 5 sample products, but ideally 12. Incorrect formatting and missing fields within this response message is the primary cause of observed plugin development bugs. To see how the response object to get dia settings is generated, see example 1 and example 2.

Use this dummy JSON response while testing or just starting your implementation. In the platform field, pass your Facebook assigned platform name (it is case-sensitive). If you don't have one, contact your Facebook representative.

  • set merchant settings—This message to your plugin sends the user's store ID when the setup is complete. You need this ID when a user returns to the popup after setting up the first time. The popup can then render a custom version of the Facebook Onboarding Flow, called the control panel. You must pass this ID to the popup URL as a GET param the next time the popup is opened. Store this ID in a datastore where it can be later retrieved if the user ever returns to the plugin; for example, SQL.

    * There is a timeout on `set merchant settings` for initial onboarding. If an `ack` response is not received within 60 seconds, the popup closes and deletes everything created. This prevents a state where Facebook objects are not sent to the plugin.
    
  • set pixel—Sends a pixel ID and a boolean showing whether advanced matching is enabled or not. Store this information and use it to insert the pixel ID on every pixel page. For details, see Install the Facebook Pixel.

    * On success, return an `ack` message as specified in the protocol. This message is sent during the initial Onboarding Flow once. If someone later updates the pixel ID through the control panel, you should be able to enable or disable advanced matching based on this message. For details, see [Supported Parameters](https://developers.facebook.com/docs/marketing-api/fbe/fbe1/reference#supported-params).
    

Support the gen feed message

Go to the Onboarding Flow control panel > Fetch Now, where it’s passed and where returning users can immediately regenerate their feed file. This is useful for store owners who updated their inventory and want to immediately sync it with Facebook. On receiving the message, your plugin should start generating the feed file and return ack gen feed when done. For details, see Supported Parameters.

Implementation details of message passing

For the Launch Screen for reference and debugging, see these examples:

Criteria for Your Plugin

The basic model your plugin should follow is to listen to messages from the Onboarding Flow popup and reply. Specifically, the Facebook Onboarding Flow popup uses window.opener.postMessage(...) to send messages to your plugin's launch screen.

Use action and reply—When a message is received, the launch screen of your plugin should do an action on your platform and send a message back to the FBE dialog box. For example, when the FBE popup sends a message to the browser asking for ‘get dia settings’, you should respond with a valid configuration using the ‘dia settings’ message. See Supported Parameters for details for these settings.

  • The launch screen window should listen for messages with window.addEventListener('message', ... ).
  • As an example, Magento uses popup.postMessage(...) to reply to the popup, where popup = window.open(...) references the popup.
  • Communicate with your launch screen—When your plugin opens the Onboarding Flow popup with window.open(...), you should provide the following parameter so that the popup can communicate with your launch screen:
?origin=<subdomain.domain of launch screen.com>

Step 1: Create a FBE popup box for new and existing users

In previous steps, you created a way for the FBE popup box to open for new and existing users.

Example—New users

fbe_popup_box = window.open(‘http://www.facebook.com/ads/dia?origin=<domainofstore>’)

Example—Return users

For return users, the merchant_settings_id should be the ID your plugin received from the set merchant settings message:

fbe_popup_box = window.open("http://www.facebook.com/ads/dia?origin=<domainofstore>&merchant_settings_id=<merchant setting>”)

Store fbe_popup variable and reference it when doing message passing to and from the FBE popup box. We recommend storing it in the browser’s window object for global access.

Step 2: FBE popup box sends a message to your browser

After the initial open, FBE popup box sends a get dia settings message to your browser. This is what FBE sends to the browser:

window.opener.postMessage({type: ‘get dia settings’, params : {}});

Example—FBE popup box

string type : "get dia settings"
object params : {}

Step 3: Your code should respond with a dia settings message

These are the settings the FBE popup box uses to determine future steps.

See Supported Parameters, Message Passing Protocol for a description of each field.

Step 4: Your FBE popup box sends a message

If you chose the API Approach, the FBE popup box sends a set catalog message. This message comes with a catalog ID.

window.opener.postMessage({type: ‘set catalog’, params: { ‘catalog_id’ : <catalog_id>}});

Store this ID in your database to update accordingly via the API.

If you chose the Feed Approach, verify that the provided feed URL in the dia settings message is correct.

Step 5: Respond to the previous message

Respond to the previous message with an ack set catalog message:

popup.postMessage({type: ‘ack set catalog’, params: {‘catalog_id’: <catalog_id>});

Step 6: FBE sends a set pixel message

If the user has never created a pixel, FBE creates one for the user.

window.opener.postMessage({type: ‘set pixel’, params: {“pixel_id” : <PIXEL ID>, “pixel_use_pii”: true}});

Step 7: Store the pixel_id into a database

Use this pixel ID to implement standard events for the merchant’s store. Once you have successfully done that, respond to the FBE popup box with an ack set pixel message.

If you did not receive a pixel_id in the set pixel message, respond to the FBE popup box with a fail set pixel message to restart this flow for the user.

popup.postMessage({type: ‘ack set pixel’ || ‘fail set pixel’ , params : {}});

See Supported Parameters for pixel_id.

Step 8: FBE sends a message

If you chose the Feed Approach: FBE sends a gen feed message to the browser. When receiving this message, you can regenerate the feed file for the catalog (the same feed URL used in the dia settings).

type : "gen feed"
params : {}

See Supported Parameters for gen feed.

Step 9: Respond with a message after regenerating the feed file

Once you have successfully finished regenerating the feed file, you can respond with an ack feed message.

If you did not successfully generate the feed file, respond with a fail feed message. The FBE popup box then shows an error.

popup.postMessage({type: ‘ack feed’ || ‘fail feed’ , params : {}});

Step 10: FBE popup box sends a set merchant settings message

After the feed is regenerated, the FBE popup box sends a set merchant settings message.

This message:

  • Contains the merchant’s Facebook ID for their store. Store the setting_id to represent the merchant's Facebook store
  • Indicates that the merchant shop is set up
type: "set merchant settings"
params : { " setting_id": <fbid of User's Store> }

See Supported Parameters for set merchant settings.

Step 11: Store the setting ID

If the setting_id was returned in the last message, it means the user successfully set up a merchant shop. You need to use this ID for future reference when opening up the popup box.

The merchant_settings_id in the URL below should be the setting_id you just received from the set merchant settings.

fbe_popup_box = window.open("http://www.facebook.com/ads/dia?origin=<domainofstore>&merchant_settings_id=<merchant setting>”)

Step 12: Send a confirmation message to the popup box

After you have the merchant setting ID, send an ack set merchant settings message to the popup box if the setting_id was received. Send a fail set merchant settings param if it was not.

popup.postMessage({type: ‘ack set merchant settings’ || ‘fail set merchant settings’ , params : {}});

Step 13: Store the page token in your database

If you chose the API approach: A set page access token message is sent to the browser. This returns the page_id and page_token fields. Store the page token in your database. This token is used for updating the product catalog.

window.opener.postMessage({type: ‘set page access token, params: {“page_id” : <page FBID>, “page_token”: <api_access_token>}});

If you chose the API approach: After you have properly received and stored the page access token and page_id, send a ack page access token message back to the popup. If you were unable to get the page access token, send a fail page access token message to the popup.

type : "ack page access token" || "fail page access token"
params : {}

Step 14: FBE popup sends a reset message

At any point, the FBE popup can send a reset message. This message is meant to notify your platform to remove all of the stored settings, pixel IDs, catalog IDs, etc for the user. See Supported Parameters for reset.

type : "reset" 
params : {}

Step 15: Send a reset confirmation message

  • If your platform successfully reset all settings, respond to the popup box with an ack reset.
  • If the reset did not work on your platform, send a fail reset message.
type : "ack reset" || "fail reset"
params : {}