Migration Guide: FBE, v1 to FBE, v2

This migration guide describes the changes required to migrate existing merchants on FBE, v1 to be compatible with FBE, v2.

Changes

As FBE, v2 significantly differs from FBE, v1 in terms of technical implementation, we strongly advise to follow FBE, v2 guides for implementation and best practices.

Business Login

When launching Business Login for FBE, v2, specify merchant_settings_id in the setup object. The merchant_settings_id in FBE, v1 is sent in message passing via set merchant settings (reference) and should already be stored on partner’s side to popup proper FBE view for returning users on FBE, v1.

Via URL

https://facebook.com/dialog/oauth?client_id=<YOUR_FB_APP_ID>
&display=<popup|window|page>
&redirect_uri=<REDIRECT_URI> // e.g. "https://partner-site.com/redirectlanding"
&response_type=token
&scope=manage_business_extension,catalog_management
&extras={
    "setup": {
        "external_business_id": "<YOUR_ID_FOR_THE_BUSINESS>", // e.g. "foo-123"
        "timezone": "<BUSINESS_TIMEZONE>", // e.g. "America/Los_Angeles"
        "currency": "<BUSINESS_SERVICES_CURRENCY>", // e.g. "USD"
        "business_vertical": "ECOMMERCE"
        "merchant_settings_id": "<MERCHANT_SETTINGS_ID_FROM_FBE_V1>",
     },
     ...
}

Via 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",
                  "merchant_settings_id": "<MERCHANT_SETTINGS_ID_FROM_FBE_V1>",
                },
                ...
            }
        });
    }

merchant_settings_id should ideally only be passed in Business Login when the user has not yet migrated to FBE, v2 successfully. When merchant_settings_id is passed in, we fetch user’s selected assets under FBE, v1 and streamline the migration process for the user.

When you provide merchant_settings_id in the FBE setup flow, the user is prompted to the following migration paths:

• If a user has admin access to all assets from FBE, v1 and their respective Business Managers, the user is prompted to a one-screen migration, as shown on the left. In this migration, a pre-selected Business Manager follows the pixel’s Business Manager because the pixel cannot be migrated to another Business Manager.

• If a user has admin access to all assets from FBE, v1, but the pixel is not owned by a Business Manager, the user is prompted to a one-screen migration, as shown on the left, but with Edit functionality. Users in this scenario can select an existing Business Manager or create a new one.

• Without admin access to all assets and their respective Business Managers, users are redirected to an error screen, as shown on the right. In this migration, they are required to follow a normal FBE setup flow and select each asset.