# Custom Updates, Invites, and Shares



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.

## Overlay-Enhanced Sharing

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`):**

```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.

```javascript
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:

![shareAsync dialog example](https://developers.facebook.com/images/games/nezp-images/shareAsync.png)

## FBInstant.inviteAsync()

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

```javascript
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:

![updateAsync example](https://developers.facebook.com/images/games/nezp-images/updateAsync.png)

```javascript
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:

```javascript
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](https://developers.facebook.com/documentation/games/build/zero-permissions/social-features/changing-contexts)** — Switch contexts from code or from overlay view buttons.
- **[Notifications](https://developers.facebook.com/documentation/games/build/zero-permissions/social-features/notifications)** — Send server-side notifications outside of game sessions.
- **[API Reference](https://developers.facebook.com/documentation/games/build/zero-permissions/api-reference#sharing-and-social-updates)** — Full parameter documentation for all sharing methods.