Facebook Games

Custom Updates

Custom Updates are a powerful feature which can send messages from the game to players which will be delivered in Messenger. These updates may also trigger notifications sent to the players. These updates can be used to broadcast big events in the game from one player, as turn reminders to prompt other players to take their turn, or for sending invitations to play with others.

Custom Updates can be fully customized and tailored to the specific event that the game is broadcasting, meaning that the message will be more impactful and likely to re-engage a player’s friends.

Custom Updates are available in the Instant Games SDK only to approved partner game developers.

Details

Custom update messages are delivered to the Messenger conversation in which the game is being played. Messages should contain the most important information from the gameplay session but are flexible enough to indicate meaningful updates about any in-game action. For example, a message from a turn-based game should indicate that a move has been completed and it is now the next player's turn.

Messages can be customized with an image, description, and a "call to action" button with custom text. They can also include a custom data blob of up to 1 kilobyte which is available to any player who opens the game from the update message; call the FBInstant.getEntryPointData method to access the data blob.

Your game can send only one consecutive message per context per session. Once your game posts an update of any type into the context, it will be blocked from posting more updates until either the context changes or another player posts an update to the context.

By default, only the last update message will be expanded for a given game in a conversation. Previous messages can be expanded by anyone in the conversation.

Feature Flow

The following table shows the flow of the Custom Updates feature.

TimelineDetails

Step 1: Player A sends a custom update

Player A plays a game round and the game sends a custom update.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: 'Player A just played their turn!',
    localizations: {
      es_LA: '¡Jugador A tomó su turno!',
    }
  },
  data: { matchID: 1234567890 }, 
});

Step 2: Player B receives the update and opens the game session

Player B receives the update message and opens the game session, which opens in the context with Player A immediately.

Step 3: Player B sends a custom update

Player B takes their turn and the game sends a custom update.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: 'Player B just played their turn!',
    localizations: {
      es_LA: '¡Jugador B tomó su turno!',
    }
  },
  data: { matchID: 1234567890 },
});

Step 4: Player A receives the update and opens the game session

Player A receives the update message and opens the game to take their turn.

Why You Should Integrate This Feature

Custom Updates help with player retention by providing reminders in Messenger to come back and take a turn or achieve the next game goal. The messages have great visibility in Messenger so they are more likely to be seen than posts in Feed which can sometimes be missed.

The messages also serve as convenient re-entry points for players who can jump straight into their favorite games with their close friends from their Messenger threads. Instead of having to navigate to the game through Facebook, players can start the game directly in Messenger.

Best Game Types for Custom Updates

Custom Updates are a perfect fit for turn-based games but the exceptional customization offered to developers means that it can be tailored to fit any game. Games that heavily rely on collaboration (or the opposite) with friends can also benefit from the direct interactions that Custom Updates provide.

Any game can find a way to leverage this feature due to the custom payload that gives developers 1,000 characters to use for any purpose. One example use for the payload would be for rewarding the message sender if the recipient joins the game from the message.

Getting Started

Custom Updates can be fully customized with an image, description, and even a Call to Action (CTA) button with custom text. By default, only the last update message will be expanded for a given game in a conversation. Earlier messages can be expanded by anyone in the conversation.

An update message can also pass along a custom data blob of up to 1kb. This data will be available to any player who opens the game from that message via FBInstant.getEntryPointData().

There's a limit of one consecutive message per context, per session. Once your game posts an update of any type into the context, it will be blocked from posting more updates until either:

  • The context changes; or
  • Another player posts an update to the context.

For example, two users can send updates back-and-forth, but a single user can't send two consecutive updates in the same session.

Because custom updates are fully customizable, usage is not limited to turn-based games. The message is flexible enough to indicate meaningful updates about any in-game action.

Best Practices

Here are a few tips for creating engaging, quality custom updates messages:

Text

The update should contain the most important information from that gameplay session and inform the player of the game's context. For example:

  • [FRIEND] just played [GAME]. It's your turn!
  • [FRIEND] beat the weekly high score in [GAME]. See if you can do better!

Write in active voice: use active voice to make your text sound lively, inviting and exciting. Examples:

  • [FRIEND] is challenging you to a [GAME] match.
  • You were challenged to a match.

Put the most important information first: make it easy to find key information at a glance. Make the value of the message clear to the reader. Examples:

  • Try [GAME] now!
  • Who doesn't like games? You should play [GAME] now!

Keep it short: the shorter the message, the more likely it is to be read. Examples:

  • Join [NAME] for a round of [GAME]!
  • If you're looking for adventure, action, and excitement, you should join your [FRIEND] and play a thrilling match of [GAME].

Stick to one idea: don't overwhelm the reader with information. Try simple, single idea prompts one at a time, and see which one performs best. Examples: Rise to the top of the leaderboard in [GAME]! Want to improve your strategy in [GAME] and rise to the top of the leaderboard?

Don't speak for the player or their opponent: don't make assumptions or speak for your players; no one likes having words put in their mouth. Examples:

  • [NAME] is inviting you to play [GAME]. Accept the challenge!
  • Come play [GAME] with me! I bet I will win!

Call to Action

Use the Call to Action button to guide the player to their next step. Use a simple verb that clearly conveys what the player will do when they click the button. For example:

  • Play
  • Join
  • Challenge
  • Help

Avoid terms like “Go”; “Yes”; “Accept” or any term that does not explain what the CTA will do when it is clicked.

Image

Custom updates currently support only base64-encoded images. If you try to put a link to an image or anything else than a base64-encoded image, the request will be invalid.

Example Player Journeys

Turn-based reminders

Improve retention by sending highly visible messages to players in a game when it is their turn to take an action.

TimelineDetails

Step 1: Player A takes a turn

Player A plays a game round and the game sends a custom update.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: 'Player A just played their turn!',
    localizations: {
      es_LA: '¡Jugador A tomó su turno!',
    }
  },
  data: { matchID: 1234567890 },
});

Step 2: Player B receives the update message and opens the game session

Player B receives the update message and opens the game session, which opens in the context with Player A immediately.

Step 3: Player B takes a turn

Player B takes their turn and the game sends a custom update.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: 'Player B just played their turn!',
    localizations: {
      es_LA: '¡Jugador B tomó su turno!',
    }
  },
  data: { matchID: 1234567890 },
});

Step 4: Player A receives the update message and opens the game session

Player A receives the update message and opens the game to take their turn.

Reward for playing with friends

Encourage players to play with their friends by offering rewards if they play together.

TimelineDetails

Step 1: Player A invites Player B

Player A invites Player B to join them in a game.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: ‘Play in a game with Player A!',
  },
  data: { inviterID: 1234567890,
  reward: 50 },
});

Step 2: Player B receives the update and opens the game session

Player B receives the update message and opens the game session, which opens in the context with Player A immediately.

Step 3: The game rewards Player A

The game checks the payload in Player B’s session and rewards Player A.

When the game opens, fetch the reward information from FBInstant.getEntrypointData().

Step 4: Game notifies Player A

Game sends an update informing Player A of their reward.

FBInstant.updateAsync({
  action: 'CUSTOM',
  cta: 'Play now!.',
  image: {base64image},
  text: {
    default: ‘You’ve earned a reward!’,
  },
  data: { inviterID: 1234567890,
  reward: 50 },
});

See Also