Bundle Configuration

Updated: Mar 3, 2026

Copy for LLM

When you upload your Instant Game as a bundle (ZIP file), you can include a configuration file called fbapp-config.json at the root of the bundle. This file tells the Instant Games platform how to configure certain behaviors for your game, such as screen orientation, SDK version, and navigation options.

The fbapp-config.json file is optional. If you do not include it, the platform will use default values for all configuration options. However, including it is recommended to ensure your game behaves consistently and to take advantage of platform features that require explicit opt-in.

File location

The fbapp-config.json file must be placed at the root level of your bundle ZIP file, alongside your index.html. It should not be inside a subdirectory.

my-game.zip
  index.html
  fbapp-config.json
  game.js
  styles.css
  assets/
    sprite.png
    sound.mp3

File format

The file must contain valid JSON. The top-level structure uses a key called instant_games to namespace all Instant Games-related configuration. Other top-level keys may exist for other Facebook platform features, but this guide covers only the Instant Games configuration.

Complete example

Here is a complete fbapp-config.json file with all supported Instant Games fields:

{
  "instant_games": {
    "platform_version": "7.1",
    "orientation": "landscape",
    "navigation_menu_version": "NAV_2"
  }
}

Supported fields

`instant_games.platform_version`

Type: String

Description: Specifies the version of the Instant Games SDK that your game targets. This tells the platform which version of the runtime and APIs your game expects.

Supported values: A version string corresponding to a released SDK version, such as "8.0", "7.1", "7.0", and so on.

Default: If not specified, the platform will use the latest stable SDK version. While this may seem convenient, it means that future SDK updates could change behavior in ways you did not anticipate. Set this explicitly to the version you developed and tested against.

Example:

{
  "instant_games": {
    "platform_version": "8.0"
  }
}

Recommendation: Always specify the platform version explicitly. When you are ready to adopt a newer SDK version, update this field, test your game thoroughly, and then upload the new bundle.

`instant_games.orientation`

Type: String

Description: Controls the screen orientation that your game supports. This setting affects how the platform presents your game on mobile devices.

Supported values:

Value	Description
`"portrait"`	The game is designed for portrait (vertical) orientation. On mobile devices, the game will be locked to portrait mode.
`"landscape"`	The game is designed for landscape (horizontal) orientation. On mobile devices, the game will be locked to landscape mode.
`"both"`	The game supports both orientations. The platform will allow the player to rotate their device, and your game is expected to adapt its layout accordingly.

Default: If not specified, the default behavior is typically "both", meaning the game will follow the device’s current orientation.

Example:

{
  "instant_games": {
    "orientation": "portrait"
  }
}

Recommendations:

Choose portrait if your game is designed for single-hand mobile play. Most casual games (match-3, endless runners, card games) work best in portrait.

Choose landscape if your game requires a wide viewport. Games with side-scrolling gameplay, multiplayer split-screen, or desktop-style interfaces often work better in landscape.

Choose both only if your game genuinely supports both orientations. Supporting both orientations requires responsive layout logic to handle different aspect ratios. If your game does not handle orientation changes gracefully, it is better to lock to a single orientation than to provide a broken experience when the player rotates their device.

Test your chosen orientation on real devices. Verify that the lock works correctly and that your game’s layout fills the screen appropriately in the specified orientation.

`instant_games.navigation_menu_version`

Type: String

Description: Controls the version of the navigation menu that appears within the Instant Games runtime. The navigation menu provides system-level controls such as a back button, mute toggle, and other platform features.

Supported values:

Value	Description
`"NAV_1"`	The original navigation menu layout.
`"NAV_2"`	An updated navigation menu layout with a refined design.

Default: If not specified, the platform uses the default navigation menu version for the current SDK version.

Example:

{
  "instant_games": {
    "navigation_menu_version": "NAV_2"
  }
}

Recommendation: Use "NAV_2" unless you have a specific reason to use the older version. The updated navigation menu provides a cleaner user experience and is the recommended option going forward.

Minimal Configuration

If your game is a straightforward portrait-oriented casual game targeting the latest SDK, a minimal configuration might look like this:

{
  "instant_games": {
    "platform_version": "8.0",
    "orientation": "portrait"
  }
}

Landscape game example

For a landscape-oriented game with the updated navigation menu:

{
  "instant_games": {
    "platform_version": "8.0",
    "orientation": "landscape",
    "navigation_menu_version": "NAV_2"
  }
}

Multi-orientation game example

For a game that supports both portrait and landscape:

{
  "instant_games": {
    "platform_version": "8.0",
    "orientation": "both",
    "navigation_menu_version": "NAV_2"
  }
}

Validation

The platform validates fbapp-config.json when you upload your bundle. If the file contains invalid JSON or unsupported values, the upload will fail and you will receive an error message in the App Dashboard.

Common validation issues include:

Invalid JSON syntax. Trailing commas, missing quotes, or other JSON formatting errors. Use a JSON validator or linter to check your file before uploading.

Unsupported orientation value. Only "portrait", "landscape", and "both" are accepted. Values like "Portrait" (capitalized) or "auto" are not valid.

Unsupported platform version. The version string must match a released SDK version. Arbitrary version numbers will be rejected.

Tips

Version control your configuration. Include fbapp-config.json in your source control alongside the rest of your game code. Changes to this file affect how your game behaves on the platform, and you should track those changes.

Test after changing configuration. Any change to fbapp-config.json should be followed by a test on the platform to verify that the new settings work as expected. Upload a new build with the updated configuration and test in a development environment.

Keep it simple. Only include fields that you need to override. The default values are sensible for most games, and adding unnecessary configuration increases the surface area for errors.

Next steps

Game Testing — Learn how to test your game on the platform after configuring your bundle.

Game Performance — Optimize your game’s loading time and runtime performance.

Quick Start — If you have not built your first Instant Game yet, start here.

SDK Reference — Full API documentation for the Instant Games SDK.