Migrating from Facebook Login for Gaming

• Gaming Profiles: A simplified, gaming-specific profile that players could create separately from their main Facebook profile. Gaming Profiles had a gaming-specific display name and avatar, and were designed to give players more control over their identity in games.
• Gaming-Specific Permissions: A permission model tailored to game use cases, including access to a player’s gaming friends (other people who played games and had a Gaming Profile), rather than the full Facebook friend list.
• Player Finder: A feature that let players discover other gamers to play with.
• Gaming Activity Sharing: APIs for sharing game achievements and activity to a gaming-specific feed.

1. Go to the App Dashboard and select your app.
2. Add the Instant Games product to your app if it is not already present.
3. Enable Zero Permissions in the Instant Games settings. See Zero Permissions for detailed instructions.

1. Remove the Facebook JavaScript SDK (sdk.js or all.js).
2. Add the Instant Games SDK to your index.html:

   <script src="https://connect.facebook.net/en_US/fbinstant.8.0.js"></script>
3. Restructure your game as a self-contained bundle (all files in a single directory with index.html at the root).
4. Add an fbapp-config.json file to configure platform behaviors. See Bundle Configuration.

FB.login(function(response) {
  if (response.authResponse) {
    var accessToken = response.authResponse.accessToken;
    var userId = response.authResponse.userID;
    // Authenticated. Proceed with game.
  }
}, { scope: 'gaming_profile,gaming_user_picture,gaming_user_friends' });

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

  FBInstant.setLoadingProgress(100);

  FBInstant.startGameAsync().then(function() {
    // Game is ready.
    var playerID = FBInstant.player.getID();

    startGame(playerID);
  });
});

Note: To display the player’s name or photo, use overlay views instead of directly accessing FBInstant.player.getName() or FBInstant.player.getPhoto(). See Displaying the Current Player’s Profile for examples.

• Display names may change. A player who used a gaming name like “DragonSlayer99” will now appear with their Facebook display name. Your game should not assume that player names are stable across the migration.
• Profile photos may change. The gaming avatar is replaced by the Facebook profile photo.
• Player IDs will change. The game-scoped player ID from FBInstant.player.getID() is different from the Facebook user ID or app-scoped user ID you received through Facebook Login for Gaming.

• If your game displays player names prominently (leaderboards, chat, friend lists), be aware that names will look different after migration.
• If your game allows custom in-game names or avatars, this transition will be less disruptive — players will retain their in-game identity even as the underlying Facebook identity changes.
• If you need to link a player’s old identity to their new Instant Games identity, you can use your backend server (via Zero Permissions) to facilitate account linking. For example, ask the player to enter a migration code, or match players based on other identifying information they provide voluntarily.

// Check if a specific permission was granted
FB.api('/me/permissions', function(response) {
  var permissions = response.data;
  var hasGamingProfile = permissions.some(function(p) {
    return p.permission === 'gaming_profile' && p.status === 'granted';
  });
  // Adjust game behavior based on granted permissions
});

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

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

// To display player names and photos, use overlay views.
// See: /documentation/games/build/zero-permissions/example-game-use-cases

FB.api('/me/friends', { fields: 'id,name,picture' }, function(response) {
  // response.data contains gaming friends
});

FBInstant.player.getConnectedPlayersAsync().then(function(players) {
  players.forEach(function(player) {
    var id = player.getID();
    var name = player.getName();
    var photo = player.getPhoto();
    // Use player data for leaderboards, friend lists, etc.
  });
});

// Gaming Activity
FB.api('/me/games.achieves', 'POST', {
  achievement: 'https://myserver.com/achievements/first_win'
});

// Share a custom update
FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play Now',
  image: base64EncodedImage,
  text: {
    default: 'I just earned my first win!',
  },
  template: 'achievement',
  strategy: 'IMMEDIATE',
  notification: 'PUSH',
});

// Client sends the access token to your server.
// Server verifies it against the Graph API:
// GET /me?access_token=USER_ACCESS_TOKEN

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

1. Account linking via ASID. Use the Cross-play management tool in the App Dashboard to link your legacy app and the Instant Game. You can access this interface through Instant Games > Audience Details. Then, in your Instant Game, call FBInstant.player.getASIDAsync() to retrieve the legacy Application-Scoped ID (ASID), which matches the user ID from your existing app. Use this to look up and merge the player’s existing backend data with their new Instant Games Player ID. This approach requires Zero Permissions for server communication. See Cross-play Management for setup instructions.
2. Manual account linking via your backend. When a player first opens the Instant Game, prompt them to link their existing account by entering their username, email, or a migration code that you provide through an out-of-band channel (email, in-game notification in the old version, etc.). This approach also requires Zero Permissions.
3. Graceful restart. For games where player progress is less critical (e.g., casual games with minimal progression), allow players to start fresh in the Instant Game. You can use the Instant Games SDK’s built-in cloud storage (FBInstant.player.setDataAsync() / FBInstant.player.getDataAsync()) for data persistence going forward.

• Authentication flow. Verify that the game loads and the player is correctly identified without any login prompt.
• Player identity. Confirm that FBInstant.player.getID(), getName(), and getPhoto() return correct values.
• Connected players. Test that friends who also play the game appear correctly.
• Sharing and updates. Test that shareAsync() and updateAsync() work and produce well-formatted posts.
• Server communication. If you use Zero Permissions, verify that your game can communicate with your server and that signed player info verification works correctly.
• Data persistence. Verify that player data saves and loads correctly, whether using SDK cloud storage or your own backend.
• Account linking. If you implemented account linking, test the complete flow including edge cases (invalid codes, already-linked accounts, etc.).

1. Audit your current integration. Identify all FB.login() calls, Graph API requests, and server-side access token verifications that need to 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 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. Set up the App Dashboard. Add the Instant Games product to your existing App ID.

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

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

• Zero Permissions Overview — Understand the full capabilities of Zero Permissions.
• Bundle Configuration — Configure your game bundle.
• Game Testing — Comprehensive testing guide.
• SDK Reference — Full API documentation.
• Get Support — Reach out if you encounter issues during migration.