Sharing improves the visibility of your game by enabling your players to share key moments or achievements. Sharing is available to all approved game developers using SDKs for Instant Games and Legacy Web Games.

Players can post meaningful moments from your game to a variety of Facebook surfaces including:

  • Player's Feed
  • Friends' Feeds
  • Messenger Conversations
  • Facebook Groups


Players can share screenshots and video clips of their gameplay. Shares to the player's Feed can include a custom message.

Call FBInstant.shareAsync() to set the image, text, and button text for the content that will appear in Feed stories and Messenger messages. When a user clicks the button it launches the game; from that entry point, the developer has access to FBInstant.getEntrypointData(), which returns the data object that was passed to FBInstant.shareAsync().

Feature Flow

The flow of the Sharing feature is as follows:

  1. Player achieves something: e.g. completes a level, beats a difficulty, gets an achievement.

    Prompt your players to share - but don’t call the API until they’ve clicked a Share button (See Facebook Developer Policy 7.4.f).

  2. After they click Share, call shareAsync and pass in an image, GIF or video that will show up in Feed, as well as a payload that can help you put new players into the right experience in-game.

    Player chooses who to share with, writes something and shares.

  3. Post shows up in Feed

    Players who jump into the game will start a brand new session, unless you provide and use a payload to drop them somewhere else.

Shares are published directly to a player's profile and show up in Feed, so to maximize player acquisition be sure to build a high quality, intuitive sharing flow into your game. When designing your games, identify meaningful moments (e.g., a feeling of personal accomplishment, an exquisite victory by a friend, or a celebration of a team effort) and give players clear options to share these moments.

We recommend at least one prominent Share button on a results page or other relevant pages. Encourage your players to share more content by providing game prompts at meaningful times, including with context / descriptions (e.g., achieved a new high score, acquired a rare item). For more details, see Best Practices.

Why You Should Integrate This Feature

This one-to-many communication channel is a powerful driver of player acquisition and retention. Because they manifest in Feed, Shares can help surface your game to players who have never seen it before—especially players who don’t usually visit the Gaming Tab.

Read how Awesome Prototype leveraged sharing to drive retention

Getting Started

This section contains information about how to integrate the Sharing feature in each supported SDK.

Instant Games

Call FBInstant.shareAsync() to initiate sharing, and pass in an image and a payload that can bring a player’s friends right into the correct game level.

  • FBInstant.shareAsync invokes a sharing dialog over the game. Developers can specify:
    • The image to be shared.
    • A payload to bring new players directly to the correct place in the game.
    • A parameter to create a context and switch the player who shares into it.

Legacy Web Games

Call FB.gamingservices.uploadImageToMediaLibrary in the Gaming Services Javascript SDK.

  • FB.gamingservices.uploadImageToMediaLibrary allows the game to upload media asynchronously (player will share after the session)
  • Setting shouldLaunchMediaDialog to TRUE triggers an immediate share dialog.

Best Practices

See advice on Sharing Meaningful Moments.

Example Player Journeys

Sharing a specific game destination/mode

Step 1: Shareable moment happens

The player makes a new discovery or completes character creation and chooses to share.

Step 2: Player edits the share and shares to Feed

Your game should make the following call.


Step 3: Friend sees share

Friend sees the share and clicks to play.

Step 4: Friend launches game

The friend jumps into the right place in the game and begins play.

Rewarded Referrals

Incentivizing players by giving rewards in return just for sharing the game is against Facebook Policy. But you can reward players if someone plays the game (and accepts TOS as needed) from a share or invite. In this case, you can reward both players, if you wish.

Step 1: Game offers reward

Your game offers to reward the player for bringing friends to the game.

Step 2: Player opts to share

Your game should make the following call.

  intent: 'REQUEST',
  Image: base64Picture,
  text: ‘Come play with your friend!’,
  data: {payload: ‘...’},
  switchContext: false,

Step 3: Friend sees share

Friend sees the share and clicks to play.

Step 4: Game rewards new player for joining

Game interprets payload and shows the person their reward from playing from the share.

Your game should make the following call.


Step 5: Game rewards inviter for sharing

When the invitee accepts the reward, send a Custom Update to the inviter to let them know they get one too.

Your game should make the following call.

  action: 'CUSTOM',
  cta: 'Join The Fight',
  image: base64Picture,
  text: {
    default: 'You have a new reward!',
    localizations: {}}
  template: 'VILLAGE_INVASION',
  data: { payload: '...' },
  strategy: 'IMMEDIATE',
  notification: 'NO_PUSH',

Feature FAQ

What’s the difference between incentivized sharing and rewarded referrals?

You are not allowed to give Player A a gift just for inviting another player or sharing something to Feed. However, Player A can receive a reward if they invite Player B, and Player B has started playing. Player B can also receive a reward in this scenario. Read more about this policy.

Documentation Contents

Sharing for Instant Games

Explains how to allow your players to share their game activity to their profile and their friends' Feed.

Sharing for Native Apps

Learn how to enable game content to be shared broadly across Facebook and Instagram.

See Also