I. Developer Platform Configuration

1.1 Register an account

1. First, it is needed to register a Facebook account.

   Please go to Facebook's official website to register an account: https://www.facebook.com, and complete account verification ( Email or cellphone verification) according to prompts.

2. Activate the developer account

   After having a Facebook account, open the Facebook developer center in the browser and activate the developer account :

   

   Agree with the agreement and continue:

   

3. Cellphone verification

   

4. Complete registration

   

1.2 Creat a new app

1. Click on the menu bar in the upper right corner to add an app

   

2. Use the basic configuration. It is OK to choose Android or iOS, and the configuration method is basically the same. It is not narrated in detail here

   

3. Fill in the basic information. Note that App type is Game

   

4. Once the verification is complete, the app is successfully created.

1.3 Configure the app

1. In Faceboook App console, when clicking the Settings menu, you can see the basic information of the app, and click "Add Platform" to add app platform

   

2. Add Android, iOS platform ( according to need to choose)

   

3. Add the corresponding configuration. You can fill it in directly, or click "Quick Start" in the upper right corner of the platform configuration to configure it according to the instructions.

   

1.4 Add user permission

1. Confirm (add) test permissions. Before the app is published, only those added to the permission list or the test user list can have the permission to use Facebook's related functions

   

1.5 Configure MSDK backend

After the game's Facebook app is completed, you need to find the MSDK backend configuration;

II. Android Project configuration

2.1 General Project Configuration

（1）Permission configuration

In AndroidManifest.xml, add the network access permission

 <uses-permission android: name="android.permission.INTERNERT"/>

（2）Activity configuration

In Application node, add the following configuration, in which the value is the string type

<activity android: name="com.facebook.FacebookActivity"
          android:configChanges="keyboard|keyboardHidden|screenLayout|screenSize|orientation"
          android:label="@string/app_name" />

（3）APP ID configuration

In the project's assets/MSDKConfig.ini file, add the following configuration

[Facebook channel configuration]
FACEBOOK_APP_ID = {YOUR_FB_APP_ID}
FACEBOOK_DISPLAYNAME = {YOUR_APP_NAME}

[info] Replace {YOUR_FB_APP_ID} with APP ID applied for by the business, {YOUR_APP_NAME} is the display name of your app.

（4）ContentProvider configuration

Under the Application node, add the following provider configuration

<provider android:authorities="com.facebook.app.FacebookContentProvider{YOUR_FB_APP_ID}"
          android:name="com.facebook.FacebookContentProvider"
          android:exported="true"/>

[info] {YOUR_FB_APP_ID} This number needs to be changed to Facebook AppID.

（5）[Optional configuration] Facebook APP ID configuration

By default, MSDK will read FACEBOOK_APP_ID in MSDKConfig.ini as Facebook APP ID. This mode is initialized when the game first calls Facebook-related services.

But the default mode:

• Uses an initialization method that Facebook no longer recommends
• In this case, Facebook may not initialized when it is logged in. This may lead to login failure

If your game wants to avoid this problem and doesn't mind that Facebook is being initialized when the game is started, you can add the following settings and add the facebook_app_id element instrings.xml. facebook_app_id needs to be filled with the APP ID applied for the game.

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id"/>

III. iOS Project Configuration

3.1 MSDKConfig configuration file

In the project, find MSDKAppSetting.bundle/MSDKConfig.ini file, and add the following configuration

[Facebook channel configuration]
FACEBOOK_APP_ID = YOUR_FACEBOOK_APP_ID
FACEBOOK_DISPLAYNAME = Your APP DISPLAY NAME

[info] Replace {YOUR_FACEBOOK_APP_ID} with APP_ID applied for by the business,{YOUR_APP_NAME} is the display name of your app.

3.2 Xcode Project Configuration File info.plist

Find or create the following node:

 <key>CFBundleURLTypes</key>
     <array>
     <dict>
        <key>CFBundleTypeRole</key>
        <string>Editor</string>
        <key>CFBundleURLName</key>
        <string>Facebook</string>
         <key>CFBundleURLSchemes</key>
         <array>
             <string>fb{your facebook app id}</string>
         </array>
     </dict>
 </array>
 <key>LSApplicationQueriesSchemes</key>
 <array>
     <string>fb-messenger-api</string>
     <string>fbshareextension</string>
     <string>fbauth2</string>
     <string>fb-messenger-share-api</string>
     <string>fbapi</string>
 </array>
 <key>NSAppTransportSecurity</key>
     <dict>
     <key>NSAllowsArbitraryLoads</key>
     <true/>
 </dict>

Where, {your facebook app id} needs to be modified into Facebook AppID applied for by the game

3.3 Unity XUPoter's xx.projmods file's configuration

When Unity exports XCode project, it needs to configure projmods file, so as to make the exported XCode project get the configuration of 3.2

{
    "group": "MSDKFacebook", 
    "libs": [], 
    "frameworks": [], 
    "files": [], 
    "folders": [], 
    "excludes": [], 
    "headerpaths": [], 
    "build_settings": {}, 
    "system_capabilities": {}, 
    "Info.plist": {
        "LSApplicationQueriesSchemes":
        [
            "fb-messenger-api",
            "fbshareextension",
            "fbauth2",
            "fb-messenger-share-api",
            "fbapi",
        ],
        "CFBundleURLTypes" :
        [
            {
                "CFBundleTypeRole":"Editor",
                "CFBundleURLName":"Facebook",
                "CFBundleURLSchemes":["fb{Facebook_APPID}"]
            }
        ]
    },  
}

Where, {Facebook_APPID} needs to be modified into Facebook AppID applied for by the game

3.4 MSDK V5.15 and later versions need to deal with UnrealEngine's Swift and Objective-C mixed compilation issues

For details, please refer to UnrealEngine supports Swift and Objective-C mixed compilation configuration on iOS platform

IV. Function Description

4.1 Login Function

Facebook can login without having to install APP

• iOS can launch the web page to login
• If Android device is installed with APP, it will launch APP to login; otherwise it will launch the Web UI to login

info On some Android phones, the newly installed Facebook cannot launch APP to log in the game. It is needed to re-start Facebook once and then re-start the game again. Only after this can Facebook launch APP. This problem is caused by the Rom problem.

4.2 Friend Function

[danger] Facebook no longer supports sending messages to Messenger, so MSDK no longer maintains Facebook sendMessage interface. Various project teams please use it with caution.
Facebook-related documentation: https://developers.facebook.com/docs/sharing/messenger

Support type list

[info] Precaution

1. Images can be local images and network images, but network images will not be saved locally.
2. Only non-game friends can be searched when the game invites friends.
3. Facebook has adjusted the strategy for sharing links. When the user sends messages and shares links, Title, content and imagePath fields are no longer valid.
4. Due to Facebook interface adjustment and MSDK policy adjustment, queryFriends, addFriend, friend batch invitation and other functions are no longer supported.
5. Support the function of inviting in-game friends in batch. It is needed to set 'inviteType' in ExtraJson to 'batch' and fill the friend ID into userList as an array;
6. The link cannot be empty when it is shared;
7. Title and Desc cannot be empty when you invite friends;
8. After friends are invited successfully, the list of friends invited by the user should be filled into ExtraJson as an array, and the corresponding key is RequestRecipients;
9. You can specify friends who require @ when sharing messages. It is needed to fill the friends requiring @ into ExtraJson as an array.

4.3 Event reporting

1.For data reporting, please refer to Event Reporting Module.

4.4 Data query

The reported results can be viewed on "Corresponding application console->View application analysis" on Facebook Developer

In the application analysis UI, you can click on the corresponding reported event to view the data according to the name of the reported event

[info] Precaution 1.When the event reporting interface is called, the reported event will have a certain degree of delay (related to network environment, Facebook side's network fluctuations and other factors), so there are often cases where there are reported event names but no detailed data. This is a normal phenomenon. It is generally recommended to view the data about half an hour after receiving the "successfully reported" callback.

V. FAQ

Precautions about Facebook's invitation function (i.e. GameRequest)

1. Avoid sending invitations frequently; otherwise, the invitations may not be received;
   
2. There is some time delay;
   
3. The Facebook management system can block messages;
   
4. If Facebook App has not been released, the invitee also needs to have the test permission to receive the invitation;
   
5. During the test process, try to use the test number to avoid the above problems;