> For the complete documentation index, see [llms.txt](https://docs.candy-smith.com/main/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.candy-smith.com/main/general-info/facebook/facebook-account-setup.md). # Facebook account setup This guide describes the Facebook and leaderboard setup for the current `HomeDesignMatch3Kit` project. The original Candy Smith guide uses the spelling `Leadboard` and describes a legacy Gamesparks/PlayFab flow. The original Facebook sequence is preserved below, while project-specific notes explain the current Unity Gaming Services (UGS) setup. Source guide: [How to setup Facebook and Leadboard](https://docs.candy-smith.com/main/general-info/how-to-setup-facebook-and-leadboard). {% hint style="info" %} The screenshots below are taken from the source guide. Meta and Unity may move controls or rename labels in newer dashboard and editor versions. {% endhint %} ## What is configured * Facebook Login through the Facebook Unity SDK. * Facebook as an identity provider in Unity Authentication. * A UGS leaderboard that stores the player's current level. * Cloud Code scripts for gifts and Facebook-to-Unity player mapping. * Optional Facebook friends access through the [`user_friends` permission](broken://pages/c2886e28faddcf298f15f215999599828e084449). ## Prerequisites Before starting, prepare the following: * A Meta developer account: [Meta for Developers](https://developers.facebook.com/apps/). * A Meta app registered for the game, or access to an existing Meta app for this game. * The Android package name and iOS Bundle ID from Unity Player Settings. * Access to the Unity organization and UGS project that will be used by the game. * A debug or release keystore and its Android key hash. * Test Facebook accounts. Do not use fake accounts; add real test users or app-role accounts in the Meta dashboard. {% stepper %} {% step %} ## Link the Unity project 1. Open the project in Unity 6000.0.80f1 or a compatible Unity version. 2. Sign in to the Unity Editor. 3. Open `HomeDesignMatch3Kit > Settings > Setup Wizard`. 4. In step 1, open Project Services and link the project to the correct Unity organization and UGS project. 5. Select the environment used for development or release. {% hint style="warning" %} The leaderboard and Cloud Code resources are created in the selected environment. Selecting a different environment later does not copy resources between environments. {% endhint %} {% endstep %} {% step %} ## Create and configure the Meta app Open the [Meta Developer Dashboard](https://developers.facebook.com/apps/), open **My Apps**, and click **Create App**. ### Create the app 1. Enter the game name. 2. Select the use case **Authenticate and request data from users with Facebook Login**. The wording may be shortened to **Authenticate and request data from users** in the current dashboard. 3. At the Business step, select the business connected to the game or continue without connecting a business. 4. Finish creating the app and open its dashboard. ![Meta Developer Dashboard](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/MjjOJF9HKyAeSkvu4VBZ/images/facebook/meta-create-app-dashboard.png) ![Meta app creation form](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/lMj7BJJQKC7Og8ukhb9b/images/facebook/meta-create-app.png)
### Basic app settings 1. Open **App settings > Basic**. 2. Set the **Category**, **Sub-category**, and **App icon** when those fields are shown. 3. Save the changes. 4. Copy the numeric **App ID**. 5. Copy the **Client Token** from the security section in **Settings > Advanced**. 6. Keep the **App Secret** private. It is required to configure Unity Authentication, but it must not be committed to the repository or stored in `LeaderboardSettings.asset`. ![Meta app basic settings](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/YHhYFm6YFnUvoycrKdw2/images/facebook/meta-app-basic-settings.png) ### Android platform Add an Android platform to the Meta app: 1. Set the package name to the exact value from `Project Settings > Player > Android > Package Name`. 2. Set the Unity deep-linking activity class to `com.facebook.unity.FBUnityDeepLinkingActivity` if the dashboard asks for it. 3. Enable Single Sign On and Deep Linking when those options are available. 4. Add every key hash used to sign the app, including separate debug and release hashes. 5. Save the platform settings. ![Add a platform in Meta](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/Cqe37i6H2uNgfCUpyBfd/images/facebook/meta-add-platform.png) ![Select Android or iOS](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/BYbMOQz3eEkFaZMJfQeg/images/facebook/meta-select-platform.png) ![Meta Android platform settings](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/aUH3xI39HzAtAPWa6Umg/images/facebook/meta-android-platform.png) {% hint style="warning" %} The package name, signing key, and Facebook App ID must belong to the same build. A key hash from a debug keystore will not authenticate a release-signed APK. {% endhint %} ### iOS platform Add an iOS platform and set its Bundle ID to the exact value from `Project Settings > Player > iOS > Bundle Identifier`. If the dashboard asks for an App Store ID or other store metadata, use the values belonging to the final iOS app. Save the platform settings. Before publishing the app, provide a valid privacy policy URL and complete the app's required verification and review steps. ![Facebook Login OAuth settings](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/4TmoW5xrYjLzVHzy5c6A/images/facebook/facebook-login-oauth-settings.png) In **Settings > Advanced**, enable **Native or desktop app** when the option is available. Keep the app in development mode while testing; switch it to Live/public only after the required review and verification steps are complete. ![Native app setting](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/HqwpG1OB3t1fMTQCYLaB/images/facebook/meta-native-app.png) ![Meta Client Token](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/cMKnwnSwULic0dYhnVcT/images/facebook/meta-client-token.png) {% endstep %} {% step %} ## Install and configure the Facebook SDK in Unity The setup wizard can install the Facebook Unity SDK used by this project. The original guide describes a manual SDK flow: download the Facebook Unity SDK package, open the `.unitypackage`, and click **Import**. Use that flow only if the setup wizard cannot install the SDK; do not import a second SDK copy. ![Facebook SDK package menu](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/mRiw8bqhB7tifbzgQy4w/images/facebook/facebook-sdk-package-menu.png) ![Facebook SDK import dialog](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/Qt6MGSly97is9fL8bDYn/images/facebook/facebook-sdk-import-dialog.png) 1. Return to `HomeDesignMatch3Kit > Settings > Setup Wizard`. 2. Open step 4, **Set up Facebook**. 3. Click **Install Facebook SDK** if the SDK is not installed. 4. Enter the Meta **App ID** and **Client Token** in the Facebook SDK Settings section. 5. Enter the **App Secret** only in the password field used by **Configure Facebook Automatically**. 6. Click **Configure Facebook Automatically**. 7. Click **Regenerate Android Manifest** if the wizard did not regenerate it successfully. ![Unity Facebook SDK settings](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/JgaEqNhRv4vSXAU6huQO/images/facebook/unity-facebook-settings.png) The original guide also shows the App ID copied from Meta into the Unity Facebook settings: ![App ID in Unity Facebook settings](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/PqUamgNev6vRvdBMhDiO/images/facebook/app-id-in-unity.png) The wizard synchronizes the App ID and Client Token with `Assets/FacebookSDK/SDK/Resources/FacebookSettings.asset`, configures iOS stripping, regenerates the Android manifest, and registers or updates the Facebook identity provider in Unity Authentication. The App Secret is used for the setup operation and is not saved in the project. ![Generated Android manifest with Facebook activities](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/z1GEopO8F1oJaZJUTlQB/images/facebook/android-manifest.png) {% hint style="warning" %} Do not import a second copy of the Facebook SDK. Duplicate SDK assemblies can produce errors such as `Facebook.Unity.Settings` being imported more than once. {% endhint %} {% endstep %} {% step %} ## Configure the UGS leaderboard 1. In the setup wizard, open step 5, **Configure the leaderboard**. 2. Set the leaderboard ID. The default value is `global_leaderboard`. 3. Set `Score Fetch Limit` and `Opponent Count` as required by the UI. 4. Click **Save Settings**. 5. Click **Configure Leaderboard**. The provisioner creates the leaderboard in the selected environment with descending sort order and `Keep Best` update behavior. Running the action again reuses an existing leaderboard with the same ID. The settings asset is stored at: ``` Assets/HomeDesignMatch3Kit/Resources/Settings/LeaderboardSettings.asset ``` The runtime submits the player's current level and reads scores through Unity Leaderboards. The current popup displays UGS leaderboard entries; it is not the legacy Gamesparks friend leaderboard. ![Facebook provider in Unity Authentication](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/N7VncB3X2MB41LSs43KP/images/facebook/unity-authentication-facebook.png) {% endstep %} {% step %} ## Enable Cloud Save and upload Cloud Code 1. In the selected UGS environment, open Cloud Save and enable it. 2. Return to the setup wizard. 3. Open step 6, **Upload and publish Cloud Code**. 4. Click **Upload Cloud Code**. The action creates or updates and publishes the included scripts for gifts and Facebook player mapping. The `facebookPlayerMappings` collection is created automatically after the first successful Facebook sign-in. If the game uses Facebook friends, complete the separate [user\_friends permission setup](broken://pages/c2886e28faddcf298f15f215999599828e084449) before testing that flow. {% endstep %} {% step %} ## Optional Meta App Center setup The original guide includes **Dashboard > App Center > Set up**. Add the game's screenshots and description there if the game should be represented in Meta's App Center. ![Meta App Center setup](https://content.gitbook.com/content/ixseEfHbM88cpcinnJo4/blobs/4HKY4p9Ul8cN5x64vkye/images/facebook/app-center-setup.png) {% endstep %} {% step %} ## Test the integration Use a device build rather than relying only on the Unity Editor: 1. Build with the same Android package name or iOS Bundle ID configured in Meta. 2. Install the build on a test device. 3. Open the Settings popup and tap the Facebook button. 4. Complete Facebook Login with an allowed test account. 5. Open the leaderboard and finish at least one level so a score can be submitted. 6. Confirm that the login completes, the UGS player is authenticated, and the score appears in the selected leaderboard. 7. If friends functionality is enabled, test it with two Facebook accounts that both use the app. {% hint style="info" %} For Unity Editor testing, the Facebook SDK uses its Mock Login Dialog and expects a valid Facebook user access token. An App ID, Client Token, or App Secret is not a user access token. {% endhint %} The original guide also includes a [video tutorial and Unity test](https://www.youtube.com/watch?v=o82n0FxOQQY). Use a device build and the navigation that exists in the submitted version of this project. {% endstep %} {% step %} ## Legacy backend note The source guide links to a paid [PlayFab setup guide](https://docs.google.com/document/d/1zBcvgZL_CcEUYwt4h2eYpi3UaKKFEcdumryk6-NcP1c) for its leaderboard, friends-on-map, and player-cloud-store flow. This project uses UGS instead, so the PlayFab/Gamesparks setup is not required for the current build. {% endstep %} {% endstepper %} ## Next steps * [Request the `user_friends` permission](broken://pages/c2886e28faddcf298f15f215999599828e084449) * [Facebook and leaderboard troubleshooting](broken://pages/a51261c0b87ef08b3476004a066545b03c3ab50d)