Authentication

Business Login

Business Login is an entry point (for example, a button) that will live on your platform’s surface (usually in an internal admin panel on your site) and trigger the Business Login flow (also known as Facebook Login). Business owners will use this login flow to associate their Facebook profiles to their business presence on your site and thus enable Facebook Business Extension features.

Requirements

Your app must complete an App review and get the following permissions:

  • catalog_management or ads_management
  • manage_business_extension

Set Up Login Flow

To set up the login flow, review these options:

  • Load Business Login via URL—Recommended if you don’t intend to use the Facebook JavaScript SDK. This option requires that you link to a dynamically generated URL per business from a button on your site.

  • Load Business Login via Facebook SDK—The Facebook SDK provides common client-side functionality. We recommend this option for developers who are more familiar with it as it offers a more standardized approach to launching the same flow.

Load Business Login via URL

To trigger Business Login via URL, place a button on your site that opens a URL.

The Business Login URL must have these query parameters:

Field Description

client_id

Type: string

Required.

Facebook App ID.

display

Type: string

Required.

Display type of Business Login: popup, window, or page.

redirect_uri

Type: string

Required.

Redirect URI that FBE redirects to after the flow is finished.

response_type

Type: string

Required.

Determines whether the Business Login response included when the redirect back to the app occurs is in URL parameters or fragments.

Use token if you need the access_token appended to the Redirect URI as a URL fragment, or code if you prefer to get the response as a URL parameter (it has to be exchanged for an access token using API call).

scope

Type: string

Required.

Permissions or scopes are needed: manage_business_extension and ads_management or catalog_management.

extras

Type: string

Required.

Contains the information regarding what flows and parameters the user will see during the flow. This includes setup and business_config. See supported extra fields.

setup

Type: string

Required.

Merchant’s Facebook setup, such as a their unique identifier (external_business_id) or currency of their catalog (currency). See supported setup fields.

business_config

Type: string

Required.

Object that FBE uses to configure the FBE workflow. See supported business_config fields.

If your app requires dynamic redirect URIs, use the state parameter to pass back the dynamic information to your redirect URI after the Business Login flow is complete.

In the example below, the extras query parameter is properly formatted and specifies both business_config and setup objects.

Example URL

https://facebook.com/dialog/oauth?
client_id=<FB_APP_ID>
&display=page
&redirect_uri="https://partner-site.com/redirectlanding"
&response_type=token
&scope=manage_business_extension,ads_management
//   alternatively use catalog_management
//   &scope=manage_business_extension,catalog_management
&extras={
  "setup": {
    "external_business_id": "foo-123",
    "timezone": "America/Los_Angeles",
    "currency": "USD",
    "business_vertical": "SERVICES"
  },
  "business_config": {
    "business": {
      "name": "Foo Business"
    },
    "page_cta": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business",
      "below_button_text": "Powered by FBE Partner"
    },
    "page_post": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business",
      "title": "Make an Appointment",
      "subtitle": "Powered by FBE Partner"
    },
    "page_card": {
      "enabled": true,
      "see_all_text": "See All",
      "see_all_url": "https://partner-site.com/foo-business",
      "cta_button_text": "Book"
    },
    "ig_cta": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    },
    "messenger_menu": {
      "enabled": true,
      "cta_button_text": "Book Now",
      "cta_button_url": "https://partner-site.com/foo-business"
    },
    "thread_intent": {
      "enabled": true,
      "cta_button_url": "https://partner-site.com/foo-business"
    }
  },
  "repeat": false
}

To manually build a Login flow, enter your redirect URL in the App Dashboard:

The redirect URL is a protection mechanism for FBE redirects. If the redirect from FBE does not match the domain in your app’s redirect URL field, FBE will not redirect to the URL at the end of the flow.

  1. Go to App Dashboard and choose your app.
  2. Scroll to Add a Product and click Set Up in the Facebook Login card.
  3. Select Settings in the left side navigation panel.
  4. Scroll to Client OAuth Settings and enter your redirect URL in the Valid OAuth Redirect URIs field.

As with a normal Facebook Login, at the end of this flow, an access_token returns, which you will use to get the pixel ID, page ID, and Instagram Business ID.

Load Business Login via Facebook SDK

Step 1. Load the Facebook JavaScript SDK

You can download the SDK and host on your platform or pull down the Facebook-hosted SDK. We recommend using the Facebook-hosted SDK.

Step 2. Attach the fbAsyncInit function to the Window object to set up the SDK settings.

Before loading the javascript SDK, the fbAsyncInit function needs to exist on the window object. The SDK will call the function to set up the proper will call window.fbAsyncInit().

This setup includes:

  • appId: Facebook App ID.
  • cookie: Enables cookies to allow the server to access this session.
  • xfbml: Parses social plugins on this page.
  • version: Tells SDK which graph API version to use (this doc was written at the time v6.0 was the latest release)

Before loading the JavaScript SDK, attach the fbAsyncInit to the window object.

Step 3. Launch FBE via the FB.login() function (also known as “Business Login”).

After loading the SDK and initializing with the proper information, use the SDK to load FB.login(). The important parameters to pass to FB.login() function are:

  1. Response callback function
  2. Object for scope and extras field
Field Description

scope

Required.

Permissions or scopes needed: manage_business_extension and ads_management or catalog_management.

extras

Required.

Contains the information regarding which flows and parameters the user sees during the FBE workflow. This includes setup and business_config.

setup

Required.

Defines the merchant’s Facebook setup such as a their unique identifier (external_business_id) or currency of their catalog (currency). See supported setup fields.

business_config

Required.

Object that FBE uses to configure the FBE workflow. See business_config supported fields.

See Facebook Business Extension API Objects and Types for details.

Example:

<script>
    window.fbAsyncInit = function() {
    //2. FB JavaScript SDK configuration and setup
        FB.init({
            appId      : '<app_id>', // FB App ID
            cookie     : true,  // enable cookies to allow the server to access the session
            xfbml      : true,  // parse social plugins on this page
            version    : 'v4.0' // uses graph api version v4.0
        });
    };

    //1. Load the JavaScript SDK asynchronously
    (function(d, s, id) {
        var js, fjs = d.getElementsByTagName(s)[0];
        if (d.getElementById(id)) return;
        js = d.createElement(s); js.id = id;
        js.src = "https://connect.facebook.net/en_US/sdk.js";
        fjs.parentNode.insertBefore(js, fjs);
    }(document, 'script', 'facebook-jssdk'));

     //3. Facebook login with JavaScript SDK
    function launchFBE() {
        FB.login(function (response) {
            if (response.authResponse) {
                // returns a User Access Token with scopes requested
                const accessToken = response.authResponse.accessToken;
                const message = {
                    'success':true,
                    'access_token':accessToken,
                };
                // store access token for later  
            } else {
              console.log('User cancelled login or did not fully authorize.');
            }
        }, {
            scope: 'catalog_management,manage_business_extension',
          // refer to the extras object table for details
            extras: {
                "setup":{
                  "external_business_id":"<external_business_id>",
                  "timezone":"America/Los_Angeles",
                  "currency":"USD",
                  "business_vertical":"ECOMMERCE"
                },
                "business_config":{
                  "business":{
                     "name":"<business_name>"
                  }
                },
                "repeat":false
            }
        });
    }
</script>

Step 4. Create a button or link to launch FBE.

To load the screen, add a button or link onClick function that calls launchFBE():

<button onclick="launchFBE()"> Launch FBE Workflow </button>

Enter your redirect URL in the App Dashboard:

The redirect URL is a protection mechanism for FBE redirects. If the redirect from FBE does not match the domain in your app’s redirect URL field, FBE will not redirect to the URL at the end of the flow.

  1. Go to App Dashboard and choose your app.
  2. Scroll to Add a Product and click Set Up in the Facebook Login card.
  3. Select Settings in the left navigation pane.
  4. Scroll to Client OAuth Settings and in the Valid OAuth Redirect URIs field, enter your redirect URL.

Latest posts