Open Graph for Games

Open Graph helps people tell stories about their lives with the apps they use. It provides developers with the opportunity to deeply integrate their app into the core Facebook experience, which enables distribution and growth. To learn about Open Graph and how to get started please refer to the Open Graph docs.

This doc walks through some best practices to get the most value out of integrating Open Graph specifically for Games.

• Leverage Common Actions - the global Scores and Achievements actions have been created to address common scenarios across many games, and are an easy way to get started with Open Graph.

• Define meaningful Actions and Objects - use the full flexibility of the Open Graph to model core user interactions in your game.

• Monitor performance with Insights - how to use Insights to monitor the performance of your Open Graph integration and iterate on your stories.

Note: To take best advantage of the Facebook News Feed, we encourage you to optimize for high-resolution Open Graph stories on both web and mobile by providing 600X600 pixel images (minimum 200X200 px).

---

Leverage Common Actions

The Scores and Achievements actions have been created to make it easy to get started publishing data to the Open Graph. They address scenarios that are common to many games.

1. Use Scores for Tournaments

Use the Graph API for Scores to publish a score for each player. Stories will be generated and shown in news feed and on timeline when a user gets a new high score, or when they pass their friends' scores.

It is possible to reset scores for all players of your game, which is useful if you have a tournament mode which periodically resets. After you reset the scores for all players, they will start again from zero and when returning to play will generate new high score and passing stories. See “Delete all scores for the app” in the Graph API for scores documentation.

Make sure you are driving users back to the tournament each time it resets so that users set a new score. One way to do this is to use the Notifications API to send timely notifications to engaged users. Also, encouraging your users to send Requests to their friends, either in the form of challenges, or free gifts, can be an effective way to keep users engaged.

Reading Scores

In addition to writing the user's score, it is also possible to read back the user's score, and the scores of all their friends in your game. This provides all the data you need in order to display a leaderboard in your game client showing where the user is placed amongst their friends. You can see an example of this being built for an HTML5 game in the Social Games Tutorial.

2. Publish Achievements that your players will be proud of

The Graph API for Achievements allows you to publish user achievements in your game. Achievements are added to a user's Timeline, and can also be surfaced to their friends through Newsfeed.

Before you begin publishing achievements, you first need to define the set of achievements in your game. You have control over the image, title and description for each achievement. Some things to keep in mind:

• Achievements should represent accomplishments that users will feel proud of.
• Focus on configuring achievements that give an idea of a user's style of game play.
• Design achievements that will make sense to a user who hasn't played your game before too.

Each achievement must also be assigned a point value, indicating how difficult it is to earn. Your achievements should have a range of difficulties - there are 1000 points to distribute amongst the achievements in your game. Scarcity is also an important factor when it comes to the distribution that achievement stories receive; users are more likely to find uncommon achievement stories interesting, and therefore achievements that are earned by fewer people are more likely to receive high distribution.

See the Graph API for achievements documentation for more information.

---

Define meaningful Actions and Objects

Once you have implemented the Scores and Achievements APIs, the next step is to define your own actions and objects. This enables you to publish activity that is not possible with the common actions, and is a key way that you can differentiate your game and publish unique and engaging content on behalf of your users.

1. Choosing the best actions and objects for your game

Before looking at best practices, here are some things to keep in mind when choosing actions and objects for your game.

• Try to capture the key components of gameplay and publish stories that represent core interactions in your game. Think about how the data you publish serves to provide a snapshot of a player’s activity in your game.

• The data that you publish should represent interactions that users are likely to be proud of and want to show off to their friends. Stories that demonstrate that a user is particularly good at certain things within a game, or spends a lot of time on a specific area, are things that a user’s friends are likely to find interesting and engage with.

• Remember that users who don’t already play your game may also see open graph stories, so try to publish data that has enough context that they understand the basics of your game and will be likely to click through and start playing.

• Focus on quality - not quantity. Stories that users engage with (via clicks, likes and comments) receive higher distribution. It is fine to have low-frequency, highly engaging actions, as well as high-frequency actions that are less engaging. Pick actions that represent core elements of gameplay.

Focus on a small number of actions to begin with; the best types of stories are those that a user will feel proud to share, and that their friends are likely to find engaging.

See Best Practices: Creating Open Graph Stories for more information.

2. Pick an interesting action and object to start

If this is your first time working with actions and objects, we recommend you check out the Open Graph Tutorial, in particular Step 4: Publish Actions for your users.

Marvel: Avengers Alliance started with a story showing that a user defeated a boss (action: defeat, object: boss). This is a key user interaction in the game, representing an important moment in a user’s gameplay. A high quality image and engaging description is used to showcase these well-known characters, maximizing potential click through rates.

3. Custom properties for more interesting stories

It is possible to define custom properties for actions, allowing you to provide additional context about this action when it is published on behalf of a user. These custom properties can be displayed in the story attachment using text templates in the action caption fields.

For example, SongPop specifies the number of seconds it took for a user to guess a song when they publish the guess action against a song object, and this is then displayed via the action caption:

4. Add social context to your stories

As with most things on Facebook, Open Graph stories are more interesting when they contain social context. There are a few different ways you can approach this.

Use the common Profile object type

The common Profile object type can be added to your app’s Open Graph configuration, and used to represent players of your game. You can then publish actions against it, or add it as a custom property to one of your existing actions.

SongPop publish a won against action against the common Profile object type in order to generate a story like the following:

Tagging Users

If user’s act together in your game in order to accomplish something, you can publish an action that represents this and tag the other user. For example, if two users complete a level by playing in co-operative mode, you could publish an action on behalf of one user and tag the other. Note that you should not use this feature if a user takes an action against another user, as they did not act together.

See tagging people for more details.

5. User Generated Objects

In some games, content is created as a user plays. Publishing this content via Open Graph can result in highly engaging stories that a user will feel proud to share and their friends are likely to engage with. As Open Graph objects are specified as web pages with meta tags, it is easy to use token replacement to dynamically generate these objects, and then immediately publish actions against them on behalf of a user.

Words with Friends uses this approach when publishing the play action against word objects. In addition, the optional action property image is used to override the default object image, and show the placement of this word placed on the game board:

6. Explicit sharing and the message parameter

If you are publishing a particularly interesting action on behalf of a user, you can give them the ability to explicitly share this content to Facebook in order to get social interactions from their friends. For example, if a user beats another player in your game, you can show a share button to allow the user to explicitly share this activity.

Actions are marked as explicitly shared by adding the fb:explicitly_shared parameter when they are published. The content is then eligible to appear as a stand-alone story in news feed, and will show on the left hand side of the user's Timeline. This enables you to drive more traffic to your game in the case where your users proactively share content to Facebook.

The Feed Dialog is another way for users to explicitly share content from your game - however, using Open Graph actions and explicit sharing is more powerful:

• Publishing is done via an API call and does not require use of Javascript dialogs
• The user interface can be tightly integrated into your game experience

It is only appropriate to use this feature in the case where a user has made a conscious decision to share their activity back to Facebook in real time - you must also give them the ability to opt out.

See How-To: Explicit Sharing for more information.

Message parameter

You can also build a user interface to prompt the user to enter a personalized message for the action, and then pass it in the message parameter when publishing the action. This message will be displayed along with the story.

Note that the text must be user generated, and cannot be pre-populated. You must request access to both the explicit sharing and message properties during the Open Graph submission flow.

---

Monitor performance with Insights

It is important to monitor how your Open Graph actions are performing in terms of distribution and referral clicks, and to continue to iterate and improve your stories to make sure you are getting the maximum possible value out of your integration.

1. Key Open Graph Insights Data

As you begin publishing data with Open Graph, familiarize yourself with some of the most important data available to you via Insights so you have an idea how your stories are performing:

Distribution and Referrals

First, you will see the number of actions published by your app, the distribution (impressions) on Facebook, and the number of referral clicks for the last month. You can limit the data to only show a particular type of action using the drop down at the top left, and control the time period to view data using the date controls at the top right.

Underneath this, you will see a breakdown showing through which channel (Newsfeed, Ticker or Timeline) the impressions and referrals are being generated. This is important data that tells you about where users are engaging with your content.

Next, you will see this data plotted over the selected time period, so you can see how your actions are performing over time. Monitor changes over time as you tweak and improve your integration.

Click Through Rates

The CTR for your stories is one of the key indicators of engagement which in turn affects distribution of your actions. It is an important data point to monitor, particularly as you make changes to the content you are publishing, or the frequency at which you are publishing data. You can find this on the Story CTR tab in Insights. This can also be filtered to show only a particular type of action or object.

Likes and Comments

Similar to CTR, Likes and Comments on your actions are another important indicator of user engagement, contributing to the distribution your stories receive. You should monitor your actions to see which get the best engagement in terms of Likes and Comments to understand what content your users like to engage with.

2. Monitor and Iterate

Once you have your Open Graph integration live and are publishing actions on behalf of users playing your game, you should monitor the data points discussed above and continue to think about how to improve your integration. Some suggestions:

• Try adding other types of actions and objects that represent different core interactions in your game. Monitor how these perform compared to the first actions and objects you created.
• Think about how you can model intentional actions in your game and give the user the ability to explicitly share these to Facebook.
• Add additional context to your stories, either with custom properties and action captions, or by adding social context as detailed in section 2. Monitor how these changes affect your story click through rates and distribution.
• Experiment with actions that are published with varying frequency levels - in general it is best to publish fewer actions that result in higher quality stories, which can optionally be explicitly shared. Monitor the total amount of referral clicks you get from each action type.

Next Steps

To learn about Open Graph and how to get started please refer to the Open Graph docs.

To learn about other ways to drive distribution for your Game please refer to the Games distribution doc.