API Reference

FBInstant.initializeAsync().then(function() {
  var locale = FBInstant.getLocale();       // e.g., 'en_US'
  var platform = FBInstant.getPlatform();   // e.g., 'IOS', 'ANDROID', 'WEB'
  var playerID = FBInstant.player.getID();

  // Load your game assets, then start
  FBInstant.setLoadingProgress(100);
  FBInstant.startGameAsync().then(function() {
    startMyGame();
  });
});

• percentage — Number between 0 and 100.

var supported = FBInstant.getSupportedAPIs();
// ['getLocale', 'initializeAsync', 'player.getID', ...]

• requestPayload(optional) — A developer-specified string (up to 1000 characters when stringified) included in the signed payload. Use this to prevent replay attacks by including a server-generated nonce.

FBInstant.player.getSignedPlayerInfoAsync('server_nonce_12345')
  .then(function(result) {
    var signature = result.getSignature();
    // Send signature to your server for verification
  });

• keys — Array of key name strings.

FBInstant.player.getDataAsync(['achievements', 'currentLife'])
  .then(function(data) {
    console.log(data.achievements);   // Array of achievement objects
    console.log(data.currentLife);    // e.g., 3
  });

• data — An object with key-value pairs to save.

FBInstant.player.getConnectedPlayersAsync()
  .then(function(players) {
    players.forEach(function(player) {
      console.log(player.getID());    // Player ID
      console.log(player.getName());  // Display name
      console.log(player.getPhoto()); // Profile photo URL
    });
  });

Zero Permissions note: Under Zero Permissions, player names and photos from getConnectedPlayersAsync() are not directly accessible to your game code. Use overlay views to render this information in a Meta-controlled iframe instead.

• id — The context ID to switch to, or "SOLO".
• switchSilentlyIfSolo(optional) — If true, skip the confirmation dialog when switching to solo. Defaults to false.

1. Single player ID — Creates a 1-on-1 context with the specified player.
2. Array of player IDs — Creates a multiplayer context with the specified players.
3. No argument — Opens a friend picker for the player to choose.

• suggestedPlayerIDs(optional) — A single player ID string or an array of player ID strings.

• options.filters(optional) — Array of ContextFilter values to limit which contexts are shown.
• options.maxSize(optional) — Maximum number of participants allowed.
• options.minSize(optional) — Minimum number of participants required.

• updateAsync() triggers a full re-render. There is no incremental DOM patching — the entire overlay is rebuilt, and all images are re-fetched, even if their src has not changed. Throttle updates to meaningful state changes, not every frame.
• dismissAsync() does not free memory. The iframe remains in the DOM with display: none. The overlay’s internal state, images, and event listeners are all preserved. There is no destroy() method. Reuse overlays with updateAsync() + showAsync() rather than creating new ones.
• Separate static and dynamic overlays. Keep frequently updated overlays (like a score HUD) small, and use a separate overlay for large static content (like a leaderboard).

• xmlPath — Path to the XML file in your game bundle (e.g., "overlay_views/profile.xml").
• domElement — The HTMLElement to attach the overlay iframe to.
• iFrameStyle(optional) — CSS styles applied to the iframe element itself.
• cssPath(optional) — Path to a CSS file for styling the overlay content.
• initialData(optional) — A data object accessible in the XML via `` template expressions.

You must call showAsync() on the returned overlay view to make it visible.

var container = document.getElementById('playerCard');

FBInstant.overlayViews.createOverlayViewAsync(
  'overlays/profile_card.xml',
  container,
  'width: 100%; height: 80px; border: none;',
  'overlays/styles.css',
  { score: 1500, rank: 3 }
).then(function(overlay) {
  overlay.showAsync();
});

• xmlPath — Path to the XML file.
• cssPath(optional) — Path to a CSS file.
• initialData(optional) — Data object for template expressions.
• onSuccess(optional) — Callback invoked on successful initialization.
• onError(optional) — Callback invoked on error.

• domElement — The HTMLElement to attach the overlay to.
• imageStyle(optional) — CSS styles for the profile picture image.
• iFrameStyle(optional) — CSS styles for the iframe container.

• domElement — The HTMLElement to attach the overlay to.
• textStyle(optional) — CSS styles for the name text.
• iFrameStyle(optional) — CSS styles for the iframe container.
• cssPath(optional) — Path to a CSS file.

• handler — A function that receives (eventStr, overlayID). eventStr is the custom event name, and overlayID identifies which overlay fired the event.

FBInstant.overlayViews.setCustomEventHandler(function(eventStr, overlayID) {
  if (eventStr.startsWith('selectPlayer_')) {
    var playerID = eventStr.split('_')[1];
    handlePlayerSelected(playerID);
  }
});

• payload.image — Base64-encoded image data.
• payload.text — Share message text. Supports `` and custom template expressions.
• payload.data(optional) — Developer payload (up to 1000 characters when stringified). Accessible in the launched session via getEntryPointData().
• payload.shareDestination(optional) — Array of destinations: 'NEWSFEED', 'GROUP', 'COPY_LINK', 'MESSENGER'.
• payload.switchContext(optional) — Whether to switch context after sharing.
• payload.imageOverlayPath(optional) — Path to an XML file for rendering player data in the share image.
• payload.pathToCSS(optional) — CSS file path for the overlay.
• payload.initialData(optional) — Data for overlay template expressions.

• payload.image — Base64-encoded image data.
• payload.text — Invitation text with default and optional localizations.
• payload.data(optional) — Developer payload (up to 1000 characters when stringified).
• payload.notificationText(optional) — Notification messaging text.
• payload.cta(optional) — Call-to-action button text.
• payload.dialogTitle(optional) — Dialog heading text.
• payload.filters(optional) — Array of filter types.
• payload.sections(optional) — Array of section configurations with max results.

FBInstant.inviteAsync({
  image: base64Picture,
  text: { default: 'Join me in this game!' },
  data: { myReplayData: '...' }
}).then(function() {
  // Invite dialog closed
});

• payload.action — Update type. Use 'CUSTOM'.
• payload.template — Template identifier (configured in the App Dashboard).
• payload.cta(optional) — Call-to-action button text.
• payload.image(optional) — Base64-encoded image.
• payload.text — Text content with default and optional localizations.
• payload.data(optional) — Developer payload (up to 1000 characters when stringified).
• payload.strategy(optional) — Delivery timing: 'IMMEDIATE' or 'LAST'.
• payload.notification(optional) — Push notification behavior: 'PUSH' or 'NO_PUSH' (default).

• payload.score — The player’s score.
• payload.data(optional) — Additional data.

Deprecated: The Global Leaderboards API is deprecated in the restricted SDK used by Zero Permissions games. All methods reject with DEPRECATED_GLOBAL_LEADERBOARD_ERROR. Use your own backend leaderboard with arbitrary player rendering instead. See Global Leaderboards for the recommended approach.

• FBInstant.globalLeaderboards.setScoreAsync(leaderboardID, score)
• FBInstant.globalLeaderboards.getScoreAsync(leaderboardID)
• FBInstant.globalLeaderboards.getTopEntriesAsync(leaderboardID, limit?)
• FBInstant.globalLeaderboards.getTopFriendEntriesAsync(leaderboardID, limit?)

FBInstant.payments.getCatalogAsync().then(function(catalog) {
  catalog.forEach(function(product) {
    console.log(product.productID, product.title, product.price);
  });
});

• config.productID — The product identifier from your catalog.
• config.developerPayload(optional) — Custom data for your server.

• appID — The target game’s Facebook App ID.
• data(optional) — Entry data (up to 1000 characters when stringified). Accessible via getEntryPointData() in the target game.

1. New module: FBInstant.overlayViews — A complete API for creating and managing overlay view iframes. Overlay views let you display player names, photos, and other profile information within your game UI while keeping that data under Meta’s control. See Overlay View Components for the XML syntax.
2. Removed APIs: FBInstant.player.getName() and FBInstant.player.getPhoto() — Direct access to player names and profile pictures has been removed to align with the Zero Permissions privacy model. Use overlay views to display this information instead.