Instant Games

Connected Players

Updated: Mar 25, 2026
Copy for LLM
Connected players are friends of the current player who have also played your game within the last 90 days. Under Zero Permissions, you can retrieve their player IDs through the SDK, but their names and profile pictures are only accessible through overlay views.
This page covers two patterns: rendering a specific friend by player ID, and rendering a full friend list.

Retrieving Connected Player IDs

Use FBInstant.player.getConnectedPlayersAsync() to get an array of connected player objects. Each object has a getID() method that returns the player’s game-scoped ID.
var connectedPlayers = await FBInstant.player.getConnectedPlayersAsync();

// Each entry is a ConnectedPlayer object
connectedPlayers[0].getID();  // e.g., '8504197016307157'
Under Zero Permissions, getName() and getPhoto() on connected player objects are not available. Use overlay views to display this information instead.

Rendering a Specific Connected Player

If you know a player’s ID (for example, from getConnectedPlayersAsync() or from your own server), you can display their name and photo in an overlay view:
XML (overlays/player_card.xml):
<View className="playerCard">
  <Image src="{{FBInstant.players[{{playerID}}].photo}}" className="avatar" />
  <Text content="{{FBInstant.players[{{playerID}}].name}}" className="name" />
</View>
JavaScript:
var container = document.getElementById('playerCardContainer');

FBInstant.overlayViews.createOverlayViewAsync(
  'overlays/player_card.xml',
  container,
  'width: 200px; height: 60px; border: none;',
  'overlays/styles.css',
  { playerID: '8504197016307157' }
).then(function(overlay) {
  overlay.showAsync();
});
The {{FBInstant.players[{{playerID}}].photo}} expression tells the overlay system to look up the player by the ID provided in initialData and display their profile picture. Your game code never sees the actual photo URL.
For rendering players who are not connected to the current player, see Arbitrary Player Rendering.

Rendering a Full Friend List

To display a list of all connected players, use the For component with FBInstant.player.connectedPlayers as the data source. This approach does not require calling getConnectedPlayersAsync() first — the overlay system resolves the connected players list automatically.
XML (overlays/friend_list.xml):
<View className="friendList">
  <For source="{{FBInstant.player.connectedPlayers}}" itemName="friend"
       sortKey="name" order="ASC">
    <View className="friendRow">
      <Image src="{{friend.photo}}" className="avatar" />
      <Text content="{{friend.name}}" className="friendName" />
    </View>
  </For>
</View>
JavaScript:
var container = document.getElementById('friendListContainer');

FBInstant.overlayViews.createOverlayViewAsync(
  'overlays/friend_list.xml',
  container,
  'width: 100%; height: 400px; border: none;',
  'overlays/styles.css'
).then(function(overlay) {
  overlay.showAsync();
});
The For loop iterates over the current player’s connected players. Each iteration provides {{friend.photo}}, {{friend.name}}, and {{friend.id}} through the item variable.

Adding Interactive Buttons

To add game actions (like “Challenge” or “Send Gift”) alongside each friend, use the onTapEvent attribute to fire custom events:
<View className="friendList">
  <For source="{{FBInstant.player.connectedPlayers}}" itemName="friend"
       sortKey="name" order="ASC">
    <View className="friendRow" onTapEvent="challenge_{{friend.id}}">
      <Image src="{{friend.photo}}" className="avatar" />
      <Text content="{{friend.name}}" className="friendName" />
      <Button content="Challenge" className="actionBtn" />
    </View>
  </For>
</View>
FBInstant.overlayViews.setCustomEventHandler(function(eventStr, overlayID) {
  if (eventStr.startsWith('challenge_')) {
    var playerID = eventStr.replace('challenge_', '');
    startChallenge(playerID);
  }
});

Next Steps