Custom Updates, Invites, and Shares

Updated: Mar 25, 2026

Copy for LLM

The Instant Games SDK provides three methods for sharing game content with players: shareAsync() for social sharing, inviteAsync() for player invitations, and updateAsync() for context updates. Under Zero Permissions, these methods continue to work as before, with the addition of overlay support for including player names and photos in shared images.

Each sharing method supports three optional properties that let you include player data in the shared image:

Property	Description
`imageOverlayPath`	Path to an XML file that defines how player data should be rendered in the shared image.
`pathToCSS`	Path to a CSS file for styling the XML overlay.
`initialData`	Data object for template expressions in the XML.

When you provide imageOverlayPath, Meta renders your XML overlay on top of the share image. This lets you include the sharing player’s name and photo without your game directly accessing that information.

Example overlay XML (overlays/share_card.xml):

<View className="shareCard">
  <Image src="{{FBInstant.player.photo}}" className="shareAvatar" />
  <Text content="{{FBInstant.player.name}} scored {{score}} points!" className="shareText" />
</View>

FBInstant.shareAsync()

Opens a dialog that lets the player share content to their timeline, Messenger, groups, or as a copied link. The promise resolves when the dialog closes, regardless of whether the player completed the share.

FBInstant.shareAsync({
  // Share image with player data overlay
  imageOverlayPath: 'overlays/share_card.xml',
  pathToCSS: 'overlays/styles.css',
  initialData: { score: 1500 },

  // Share text (supports template expressions)
  text: '{{FBInstant.player.name}} is asking for your help!',

  // Developer payload (accessible via getEntryPointData() in launched sessions)
  data: { myReplayData: '...' },

  // Where the player can share to
  shareDestination: ['NEWSFEED', 'GROUP', 'COPY_LINK', 'MESSENGER'],

  // Whether to switch context after sharing
  switchContext: false,
}).then(function() {
  // Dialog closed
});

Template expressions like {{FBInstant.player.name}} work in the text property even without an overlay — Meta resolves them at render time.

The following screenshot shows the shareAsync dialog:

FBInstant.inviteAsync()

Opens a dialog that lets the player invite friends to the game. Supports localized text, custom sections, and friend filtering.

FBInstant.inviteAsync({
  image: base64EncodedImage,
  text: {
    default: 'Come play with me!',
    localizations: {
      es_ES: 'Ven a jugar conmigo!',
      fr_FR: 'Viens jouer avec moi !'
    }
  },
  data: { referrer: FBInstant.player.getID() },
  cta: 'Play Now',
  dialogTitle: 'Invite Friends',
}).then(function() {
  // Invite dialog closed
});

FBInstant.updateAsync()

Sends a custom update to the current context, notifying other players about a game event. This is how you communicate turn changes, score updates, challenge completions, and other events to players in the same context.

The following screenshot shows an updateAsync message:

FBInstant.updateAsync({
  action: 'CUSTOM',
  template: 'turn_complete',      // Template ID (configured in App Dashboard)
  cta: 'Your Turn',
  image: base64EncodedImage,
  text: {
    default: '{{FBInstant.player.name}} just finished their turn!',
  },
  data: { turnData: '...' },
  strategy: 'IMMEDIATE',          // 'IMMEDIATE' or 'LAST'
  notification: 'PUSH',           // 'PUSH' or 'NO_PUSH' (default)

  // Optional: overlay for the update image
  imageOverlayPath: 'overlays/turn_card.xml',
  pathToCSS: 'overlays/styles.css',
  initialData: { score: currentScore },
}).then(function() {
  // Update sent
});

Strategy Options

IMMEDIATE — The update is sent right away. Use for time-sensitive events like turn notifications.

LAST — Only the most recent update with this strategy is delivered when the recipient opens the game. Use for status updates where only the latest matters.

Notification Options

NO_PUSH (default) — No push notification is sent. The update appears when the recipient opens the game.

PUSH — A push notification is sent. Use sparingly for high-signal updates to avoid over-notifying players.

Context Switching After Shares

When a player shares to a Messenger conversation, you may want to switch the game context to that conversation. Use FBInstant.onContextChange() to detect when this happens:

FBInstant.onContextChange(
  function(contextID) {
    // Game context switched — reload game state
    loadGameForContext(contextID);
  },
  function(error) {
    console.log('Context switch cancelled or failed');
  }
);

Important Notes

Data size limit: The data payload must be 1000 characters or fewer when stringified.

CSS positioning:position: absolute can cause rendering issues in overlay views. Use position: relative with flexbox as a workaround.

Push notification default: Notifications default to NO_PUSH. Only use PUSH for high-value, time-sensitive updates.

Template IDs: The template field in updateAsync() must reference a template configured in the App Dashboard.

Next Steps

Changing Contexts — Switch contexts from code or from overlay view buttons.

Notifications — Send server-side notifications outside of game sessions.

API Reference — Full parameter documentation for all sharing methods.