General FBE iFrame Guidelines

Partner Developer Guideliens

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.

Requirements for Rendering Third-Party Auth Window in iframe

HTTP Response Headers

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:

• Allow Facebook to render your page in an iframe:
  • Add/modify the Content-Security-Policy HTTP response header to include "frame-ancestors 'self' *.facebook.com *.internalfb.com;"
• Prevent browsers from blocking iframe rendering of your page:
  • Remove X-Frame-Options HTTP response header with value of DENY directive
• Enable sending cookies for requests initiated in iframed resources:
  • Modify Set-Cookie HTTP response header to include “SameSite=None;Secure”
    • Requests must be made via HTTPS protocol
    • Note: Standards related to the Cookie SameSite attribute recently (2021) changed. See here for more.

Design Requirements

• Third party partner authentication pages will be rendered at 808px by 603px. Pages should be mobile-friendly to correctly render the pages
• Disable < input > auto-focus. Most modern browser windows will block autofocusing in cross-origin subframes (and display errors to that effect.)

Post Messages

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.

Security Requirements

Due to the inherent security vulnerabilities of cross-origin communication, we will enforce the following web security standards for postMessage communication:

• For postMessages, these must specify targetOrigin (second param)
  • Use 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(\/.*)?

• Otherwise, 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:

Events

Authentication

{
  event: “auth_page_loaded”,
  payload: null
}

{
  event: “sso_signin_started”,
  payload: null
}

{
  event: “sso_signin_completed”,
  payload: null

}

{
  event: “existing_user_signin_started”,
  payload: null
}

{
  event: “existing_user_signin_completed”,
  payload: null
}

{
  event: “new_user_account_creation_started”,
  payload: null
}

{
  event: “new_user_account_creation_completed”,
 payload: null
}

{
  event: “new_user_account_post_creation_setup”,
  payload: null
}

Connection

{
  event: “fbe_onboarding_started”,
  payload: null

}

{
  event: “fbe_onboarding_completed”,
  payload: null

}

{
  event: “send_fbe_uri_extras”,
  payload: {
    uri_extras: “{‘setup’:{‘external_business...”
  }
}

Engagement

{
  event: “partner_landing_page_loaded”,
  payload: null
}

{
  event: “template_selected”,
  payload: null
}

{
  event: “platform_authorized”,
  payload: null
}

{
  event: “template_created”,
  payload: null
}

{
  event: “task_completed”,
 payload: null
}

Error Reporting

{
  type: “platform_error”,
  payload: {
    error_message: “descriptive error message”,
external_business_id : “business123456”
  }
}

Learn More

• How to do a Business Apps integration
• How to use Business Login for FBE
• extras
• business_config
• setup
• How to uninstall FBE