# Facebook Login for Gaming to Instant Games (Zero Permissions)


Facebook is deprecating Facebook Login for Gaming and Gaming Profiles to consolidate its gaming platform experiences into a single, unified model. This guide provides a step-by-step process for migrating your game to the Instant Games platform with Zero Permissions.

## Key differences between Facebook Login for Gaming and Instant Games

Before starting the migration, it is important to understand the architectural and conceptual differences between the two models.

| Aspect | Facebook Login for Gaming | Zero Permissions (Instant Games) |
|--------|--------------------------|----------------------------------|
| **Login flow** | Explicit login dialog where players grant permissions. You receive an OAuth access token. | No login flow. Players are automatically authenticated. No access token is provided; identity is accessed via `FBInstant.player`. |
| **Permissions** | Granular permissions requested at login (for example, `gaming_profile`, `gaming_user_friends`). | A single Terms of Service (TOS) window appears if the player has not yet accepted the Zero Permissions TOS. This only needs to happen once per account. |
| **Server communication** | Standard HTTPS calls using an access token for Facebook API calls. | Requires [Zero Permissions](index) to be enabled for external server communication. Uses signed player info for verification instead of an access token. |
| **Profile type** | Gaming Profile (gaming-specific name and avatar) or Real Profile. | Facebook profile. Use `FBInstant.player.getID()` for the Player ID. Use `FBInstant.player.getASIDAsync()` to retrieve ASIDs for users migrating from your existing app. |
| **Player ID** | Facebook user ID (may be app-scoped). | Game-scoped player ID from `FBInstant.player.getID()`. This is different from the Facebook user ID. |
| **Friends list** | Graph API `/me/friends` with gaming permissions. | `FBInstant.player.getConnectedPlayersAsync()` returns friends who also play the game. |
| **Sharing** | Graph API posts, Gaming Activity API. | `FBInstant.shareAsync()`, `FBInstant.updateAsync()`. |

## Step-by-step migration guide

### Step 1: Set up Instant Games on your app

If your game already has a Facebook App ID, navigate to the [App Dashboard](https://developers.facebook.com/apps/), select your app, and add the **Instant Games** product. Next, navigate to the Instant Games settings and enable **Zero Permissions**. Zero Permissions is required if your game communicates with any external servers (for example, for multiplayer, analytics, or backend logic). See [Zero Permissions](index) for detailed instructions.

### Step 2: Convert your game to an Instant Game bundle

If your game is a web game, remove the legacy Facebook JavaScript SDK (`sdk.js` or `all.js`) and include the Instant Games SDK:

```html
<script src="https://connect.facebook.net/en_US/fbinstant.8.0.js"></script>
```

Restructure your game as a self-contained bundle (all files in a single directory with `index.html` at the root). Add an `fbapp-config.json` file to configure platform behaviors. See [Bundle Configuration](https://developers.facebook.com/documentation/games/build/bundle-configuration) for details.

If your game is a native mobile game, you must port it to HTML5 using a framework like Phaser, PixiJS, Unity WebGL, or Cocos2d-x.

### Step 3: Replace the login flow

Remove the explicit `FB.login()` calls. In Instant Games, players are automatically authenticated. Replace the login flow with the Instant Games loading lifecycle:

```javascript
FBInstant.initializeAsync().then(function() {
  // Player is already authenticated. No login flow needed.

  // Load your game assets and report progress.
  FBInstant.setLoadingProgress(100);

  FBInstant.startGameAsync().then(function() {
    // Game is ready. Retrieve the player ID.
    var playerID = FBInstant.player.getID();
    startGame(playerID);
  });
});
```

### Step 4: Handle the profile transition

Gaming Profiles are being retired. Players will now use their regular Facebook profiles.

- **Display names and photos:** Players' names and avatars will change to their Facebook profile data. Use overlay views to display player names and photos rather than rendering them directly in your game canvas. See [Overlay View Components](https://developers.facebook.com/documentation/games/build/zero-permissions/overlay-view-components) for details.
- **Player IDs:** The Instant Games Player ID is game-scoped and differs from the legacy Facebook user ID.

### Step 5: Update permission checks

Remove all permission-checking logic (for example, checking for `gaming_profile` or `gaming_user_friends`). The Instant Games SDK provides a fixed set of capabilities automatically, so UI flows handling "permission denied" states are no longer necessary.

```javascript
// Player ID is always available after initializeAsync()
var playerID = FBInstant.player.getID();

// Connected players are always available (no permission needed)
FBInstant.player.getConnectedPlayersAsync().then(function(players) {
  // These are friends who also play your game
});
```

### Step 6: Update social features

- **Friends list:** Replace Graph API `/me/friends` calls with `FBInstant.player.getConnectedPlayersAsync()`.
- **Sharing and activity:** The Gaming Activity API is deprecated. Use `FBInstant.updateAsync()` and `FBInstant.shareAsync()` to share game events and custom updates.

### Step 7: Update server-side identity verification

Since there is no access token in Instant Games, you must update how your backend verifies players.

1. Use `FBInstant.player.getSignedPlayerInfoAsync('your_payload')` on the client.
2. Send the resulting signature to your backend.
3. Your server must verify the signature using your App Secret.

```javascript
FBInstant.player.getSignedPlayerInfoAsync('my_server_nonce')
  .then(function(result) {
    var signature = result.getSignature();
    // Send signature to your server for verification
    fetch('https://myserver.com/verify', {
      method: 'POST',
      body: JSON.stringify({ signature: signature })
    });
  });
```

See the [SDK Reference](https://developers.facebook.com/documentation/games/sdk-reference) for full details on signature verification.

### Step 8: Migrate player data

Because Player IDs are changing, you must map legacy accounts to new Instant Games Player IDs.

**Account linking with ASIDs:** Use the **Cross-play management** tool in the App Dashboard to link your legacy app and the Instant Game. Access this interface through **Instant Games** > **Audience Details**. Then, use `FBInstant.player.getASIDAsync()` to retrieve the legacy Application-Scoped ID (ASID) and merge the accounts on your backend. See [Cross-play Management](https://developers.facebook.com/documentation/games/build/zero-permissions/onboarding-and-migration/cross-play-management) for setup instructions.

**Graceful restart:** For simple games, you may choose to let players start fresh using the SDK's built-in cloud storage (`FBInstant.player.setDataAsync()`).

### Step 9: Test the migrated game

Test your game thoroughly using test users in the App Dashboard. Verify the authentication flow, connected players, sharing APIs, server communication (via Zero Permissions), and data migration logic. See [Game Testing](https://developers.facebook.com/documentation/games/build/game-testing) for a complete guide.

## Migration checklist

### Pre-migration preparation

1. **Audit current integration.** Identify all `FB.login()` calls, Graph API requests, and server-side access token verifications that must be replaced.
2. **Plan data migration.** Decide whether to implement account linking via ASIDs or allow a graceful restart. If linking, configure the [Cross-play management](https://developers.facebook.com/documentation/games/build/zero-permissions/onboarding-and-migration/cross-play-management) tool in the App Dashboard.
3. **Evaluate engine porting.** If migrating a native mobile game, select an HTML5 framework (for example, Unity WebGL or Phaser) and scope the porting effort.
4. **App Dashboard setup.** Add the Instant Games product to your existing App ID.

### During migration (development)

5. **Bundle restructuring.** Create a self-contained bundle with `index.html` and `fbapp-config.json`.
6. **SDK replacement.** Remove the legacy Facebook JavaScript SDK and integrate `fbinstant.8.0.js`.
7. **Implement loading flow.** Replace login dialogs with `initializeAsync()`, `setLoadingProgress()`, and `startGameAsync()`.
8. **Update identity and server verification.** Replace access token backend validation with `getSignedPlayerInfoAsync()` signature verification.
9. **Migrate social APIs.** Replace Graph API calls with `getConnectedPlayersAsync()`, `shareAsync()`, and `updateAsync()`.
10. **Implement data migration.** If applicable, implement `getASIDAsync()` to map legacy ASIDs to the new Player ID and merge backend data.
11. **Enable Zero Permissions.** Toggle Zero Permissions in the App Dashboard to allow HTTPS communication with your backend.

### Post-migration (testing and launch)

12. **Local testing.** Test the core game loop locally using a mock SDK or local HTTPS server.
13. **Platform testing.** Upload the ZIP bundle to Web Hosting and test on the Facebook platform (iOS, Android, and desktop web).
14. **Social testing.** Use App Dashboard test users to verify that connected players and sharing features work correctly without permission prompts.
15. **Data migration testing.** Test the account linking flow to ensure legacy players do not lose their progress.
16. **App review.** Submit the game for Instant Games Quality Review and ensure all configurations (Privacy Policy, App Domains) are complete.
17. **Push to production.** Switch the App Mode to **Live** and push the tested bundle to production.

## Next steps

- **[Zero Permissions Overview](index)** — Understand the full capabilities of Zero Permissions.
- **[Bundle Configuration](https://developers.facebook.com/documentation/games/build/bundle-configuration)** — Configure your game bundle.
- **[Player Identification Post Migration](https://developers.facebook.com/documentation/games/build/zero-permissions/onboarding-and-migration/player-identification-post-migration)** — Map player identifiers between your legacy app and Instant Games.
- **[SDK Reference](https://developers.facebook.com/documentation/games/sdk-reference)** — Full API documentation.
- **[Get Support](https://developers.facebook.com/documentation/games/support/index)** — Reach out if you encounter issues during migration.