To enable a more seamless user experience within Business Apps and better support the creation of new accounts on your platform, we recommend that you enable your authentication URL to load in an iframe on a Facebook surface. Follow the guidelines below to ensure that your iframe is set up correctly.
To ensure that FBE partner authentication pages can be properly rendered in an iframe on the Facebook surface, please implement the following HTTP response headers:
"frame-ancestors 'self' *.facebook.com *.internalfb.com;"
DENY
directive“SameSite=None;Secure”
< input >
auto-focus. Most modern browser windows will block autofocusing in cross-origin subframes (and display errors to that effect.)We will require communication between the FBE partner authentication page rendered in an iframe and the Facebook surface via the window.parent.postMessage()
API for certain events in order to provide the best user experience.
Due to the inherent security vulnerabilities of cross-origin communication, we will enforce the following web security standards for postMessage
communication:
document.referrer
; ensure document.referrer
matches the following regex:https?:\/\/(www\.|m\.|l\.|web\.|business\.)?(\d{4,5}\.od\.)?(business\.)?(facebook|internalfb|instagram|whatsapp)\.com(\/.*)?
postMessage
data could be intercepted by unintended third parties.The postMessage
data should be a JSON block with event
and payload
keys. The required events to communicate are summarized below:
Key | Required | Type | Purpose |
---|---|---|---|
payload | Yes | JSON object | Contains further keys as specified based on event type. See table below. |
event | Yes | String | Denotes the advertiser’s position in the integration flow. Have a look at the table below for a list of events for Zapier to emit. |
Event | Description |
---|---|
{ event: “auth_page_loaded”, payload: null } | The authentication page was successfully rendered to the user. |
{ event: “sso_signin_started”, payload: null } | User initiates the sign in / account creation flow with an SSO service (for example, Google account, FB Login). |
{ event: “sso_signin_completed”, payload: null } | User successfully signs in with an SSO service (for example, Google account, FB Login). |
{ event: “existing_user_signin_started”, payload: null } | User initiates the sign in flow with their non SSO credentials. |
{ event: “existing_user_signin_completed”, payload: null } | User successfully signs in with their non SSO credentials. |
{ event: “new_user_account_creation_started”, payload: null } | User initiates the process to create a new account. |
{ event: “new_user_account_creation_completed”, payload: null } | User successfully creates a new account. |
{ event: “new_user_account_post_creation_setup”, payload: null } | User is redirected to the third-party surface to complete account configuration after a basic account is created. This is the likely user journey in cases where a new user account will require additional setup to be viable for FBE (for example, Commerce Onboarding requires a third-party user account to have inventory). |
Event | Description |
---|---|
{ event: “fbe_onboarding_started”, payload: null } | If using Business Login - the FBE flow is invoked. |
{ event: “fbe_onboarding_completed”, payload: null } | If using Business Login - the FBE flow successfully returns an access token back to the app. |
{ event: “send_fbe_uri_extras”, payload: { uri_extras: “{‘setup’:{‘external_business...” } } | After existing user authentication or new user creation, partner sends encoded extras with |
Event | Description |
---|---|
{ event: “partner_landing_page_loaded”, payload: null } | The main post-authentication landing page is successfully rendered to the user. |
{ event: “template_selected”, payload: null } | For Creative: a user selects a creative template. For Data integration: the user selects a data feed template. |
{ event: “platform_authorized”, payload: null } | For Data integration: when the user successfully authenticates the platform they intend to integrate with Facebook. |
{ event: “template_created”, payload: null } | For Creative and Data integration: The user successfully creates a creative / data feed using a template. |
{ event: “task_completed”, payload: null } | For Creative: the user downloads the creative / successfully uploads it to Facebook. For Data integration: the user enables the feed. |
Event | Description |
---|---|
{ type: “platform_error”, payload: { error_message: “descriptive error message”, external_business_id : “business123456” } } | Any error that happens along the user journey on third party site. |
extras
business_config
setup