Instant Games

Changing Contexts

Updated: Mar 25, 2026
Copy for LLM
A context represents the social setting of a game session — a Messenger conversation, a Facebook post thread, or a solo session. Changing contexts is how players start playing with specific friends, join group games, or return to solo play.
There are two ways to change contexts: from your game’s JavaScript code using SDK methods, or directly from overlay view buttons using context actions.

Changing Contexts via SDK

The FBInstant.context module provides methods for switching contexts programmatically. See the API Reference for full method signatures.

Create a Context with a Specific Player

// Start a 1-on-1 game with a friend
FBInstant.context.createAsync('8504197016307157').then(function() {
  // Context created — reload game state for the new context
  var contextID = FBInstant.context.getID();
  loadGameForContext(contextID);
});

Let the Player Choose

// Open the friend/group picker
FBInstant.context.chooseAsync().then(function() {
  var contextID = FBInstant.context.getID();
  loadGameForContext(contextID);
});

Switch to a Known Context

// Switch to a specific context (e.g., returning to an existing game)
FBInstant.context.switchAsync('context_id_here').then(function() {
  loadGameForContext(FBInstant.context.getID());
}).catch(function(error) {
  if (error.code === 'SAME_CONTEXT') {
    // Already in this context — no action needed
  }
});

Changing Contexts from Overlay Views

You can trigger context changes directly from buttons in an overlay view, without roundtripping through your game’s JavaScript. This is useful for “Play” or “Challenge” buttons alongside friend names.

Context Create Action

Creates a new context with the specified player when the button is tapped:
<View className="friendList">
  <For source="{{FBInstant.player.connectedPlayers}}" itemName="friend">
    <View className="friendRow">
      <Image src="{{friend.photo}}" className="avatar" />
      <Text content="{{friend.name}}" className="friendName" />
      <Button content="Play" action="{{FBInstant.action.contextCreate({{friend.id}})}}"
              className="playBtn" />
    </View>
  </For>
</View>

Context Switch Action

Switches to an existing context by ID:
<Button content="Rejoin" action="{{FBInstant.action.switchContext({{contextID}})}}"
        className="rejoinBtn" />

Handling Context Changes

When a context change occurs — whether triggered from your JavaScript code or from an overlay view action — you can register callbacks to respond:
FBInstant.onContextChange(
  function(contextID) {
    console.log('Switched to context:', contextID);
    // Reload game state, update UI, etc.
    loadGameForContext(contextID);
  },
  function(error) {
    console.log('Context change failed:', error);
    // Handle the error — player may have cancelled
  }
);
This is especially important when using overlay view context actions, since the context change happens outside your game code. Without onContextChange, your game would not know that the context has changed.

Custom Events for Advanced Interaction

If you need more control than context actions provide — for example, if you want to run game logic before switching contexts — use custom events instead of context actions:
XML:
<View className="friendList">
  <For source="{{FBInstant.player.connectedPlayers}}" itemName="friend">
    <View className="friendRow" onTapEvent="challengeFriend_{{friend.id}}">
      <Image src="{{friend.photo}}" className="avatar" />
      <Text content="{{friend.name}}" className="friendName" />
      <Button content="Challenge" className="challengeBtn" />
    </View>
  </For>
</View>
JavaScript:
FBInstant.overlayViews.setCustomEventHandler(function(eventStr, overlayID) {
  if (eventStr.startsWith('challengeFriend_')) {
    var playerID = eventStr.replace('challengeFriend_', '');

    // Run your game logic first
    prepareChallengeData(playerID).then(function() {
      // Then create the context
      return FBInstant.context.createAsync(playerID);
    }).then(function() {
      startChallengeGame();
    });
  }
});
Note: Custom event names cannot contain data template expressions like {{FBInstant.player.name}}. They can contain player IDs and other literal strings or template references to your own initialData values.

Next Steps