The Graph API for achievements allows game developers to publish user achievements in their game to provide more meaningful and relevant stories.

Note: This API is only available to applications categorized as 'Games'. You can categorize your app as 'Games' in the Developer app by navigating to About > Basic Info and selecting 'Games` in the drop down menu in the category field.

An app can define a set of achievements for their app using the game.achievement object type.

• Each achievement has points associated with it.
• Each game gets a total of 1000 points to distribute across all their achievements.
• Each game gets a maximum of 1000 achievements.
• Achievements which are scarcer and have higher point values will receive more distribution. For example, achievements which have point values of less than 10 will get almost no distribution. Apps should aim for between 50-100 achievements consisting of a mix of 50 (difficult), 25 (medium), and 10 (easy) point value achievements.
• One user can achieve a particular achievement for a game only once.
• It is against policy to ever delete an achievement, except in the case of testing achievements.

Defining the set of achievements for a Game

Each achievement must possess a unique URL with the appropriate Open Graph protocol <meta> tags. We will scrape the achievement’s unique URL and use the information provided in the tags to generate the Ticker stories. The Ticker stories will redirect to the achievement’s unique URL.

When defining an Achievement URL consider that if your Achievement URL is a child of your Canvas URL, the Achievement URL will automatically be re-written as child of your Canvas Page URL. This is to prevent a user from being redirected off Canvas when clicking on an Achievement story in Ticker for a Canvas game.

For example, assume your game is hosted at www.example.com/my_game/ and playable on Canvas at apps.facebook.com/my_game/:

• Registering an Achievement URL of www.example.com/my_game/ach1.html will be re-written to apps.facebook.com/my_game/ach1.html.
• Registering an Achievement URL of www.example.com/achievements/ach1.html will not be re-written, as it is not a child of www.example.com/my_game/.

As a best practice when registering Achievement URLs for Canvas games build off your Canvas Page URL. Based on the example above, developers would register apps.facebook.com/my_game/ach1.html.

Name	Description	Required
og:type	The value should be game.achievement.	true
og:title	Achievement's title.	true
og:url	The unique URL of the achievement.	true
og:description	An achievement's description. This should explain how the achievement is earned.	true
og:image	An image URL which should represent your object within the graph. The image must be at least 50px by 50px and have a maximum aspect ratio of 3:1. We support PNG, JPEG and GIF formats. You may include multiple og:image tags to associate multiple images with your page.	true
game:points	Number of points that this achievement is worth. Total points per game may not exceed 1000 points limit, which we enforce.	true
fb:app_id	The App ID that owns this achievement.	true

Create

You can register an achievement for a game by issuing an HTTP POST to APP_ID/achievements with an app access_token and the following parameters.

Name	Description	Type	Required
achievement	Unique URL to the achievement.	string	yes
display_order	Order of this achievement as it shows up in the achievement stories UI (low to high). For example a display order of 100 will be displayed in the UI before 200. We use this value to surface achievements according to the order the developer has specified. Please make sure this value is unique and increments in the correct order for your achievements.	integer	no

Response:

Description	Type
true or error depending on whether the registration was successful.	boolean

Error Code	Description
100	Service error
3401	If an app tries to register more than the maximum number(1000) of achievements.
3402	When the app tries to register an achievement that would raise the app’s point total above the 1000-point limit.

Read

You can get all achievements for an app by issuing an HTTP GET request to /APP_ID/achievements with an app access_token. This will return an array of achievement objects where each achievement object has the following fields.

Name	Description	Type
id	ID of the achievement object.	string
type	The value should be games.achievement.	string
title	Achievement’s title.	string
url	The unique URL of the achievement.	string
description	An achievement’s description.	string
image	image for the achievement.	an array of objects, containing a URL for the image.
data	An object containing the points field which contains the number of points that this achievement is worth. Total points per game may not exceed 1000 points limit, which we enforce.	an object containing points
updated_time	Time when the achievement was last updated.	string containing an ISO-8601 datetime
context	contains context of the achievement for the associated app.	array containing the display_order

Delete

You can un-register an achievement for a game by issuing an HTTP DELETE request to /APP_ID/achievements with an app access_token and the following parameter.

Name	Description	Type	Required
achievement	The unique URL to the achievement.	string	yes

Response

Description	Type
true or error depending on whether the delete was successful.	boolean

When a developer deletes an achievement, it un-registers it from the app which means

• The app will no longer be able to publish that achievement for a user.
• The point value of the achievement is deducted from the app’s achievements point total.
• All existing user achievements for that achievement will not show up in the UI though they will still be available via the API.

Update

A developer may update the <meta> tag property values of their achievement by forcing a re-scrape of it’s Open Graph URL using the Facebook Linter. Please note that after a significant number of publishes, the property values are locked and cannot be edited.

A developer may update the custom properties of an achievement registration (e.g. display_order) by re-POSTing with the same achievement parameter value, but with an updated custom registration property value.

Managing achievements for a user

This section provides details about the API to post, and delete achievements for a user.

Read

You can read the set of achievements for a user by issuing an HTTP GET request to /USER_ID/achievements with a an app or user access_token as long as the user has given the app publish_actions permission. This returns an array of achievement(instance) objects where each achievement(instance) represents the instance of the achievement achieved by the user.

• If the user has authorized your app with the user_games_activity permission then this returns the achievements for all games. Otherwise it returns achievements only for your app.
• If the user has authorized your app with the friends_games_activity permission then you can also access achievements for the user's friends by issuing a HTTP GET request to /FRIEND_ID/achievements.

The achievement(instance) object has the following fields:

Name	Description	Type
id	ID of the achievement(instance) object.	string
from	The user who achieved the achievement.	object containing the id and name of user.
created_time	Time at which the achievement was achieved.	string containing an ISO-8601 datetime
application	The application in which the user achieved the achievement.	object containing id and name of application.
achievement	The achievement object that the user achieved.	object containing the id, url, type, and title of the achievement.
likes	Likes received by the story.	object containing the count of likes, as well as an array containing the name and id of users who like it.
comments	Comments received by the achievement story.	object containing the count of comments, as well as an array containing id of the comment, from object containing the name and id of users who created the comment, message and created_time of the comment

Create

You can post an achievement for a user by issuing an HTTP POST request to /USER_ID/achievements with an app access_token as long as the user has given the app the publish_actions permission. The API takes the following parameters:

Name	Description	Type	Required
achievement	The unique URL of the achievement which the user achieved.	string	yes

Response

Name	Description	Type
id	achievement (instance) id for that user.	string

Error Code	Description
3403	If the app tries to post an achievement which isn't registered.
3501	If the app tries to post an achievement which the user already has.

Delete

You can delete an achievement for a user by issuing an HTTP DELETE request to USER_ID/achievements with the app access_token as long as you have the publish_actions permission.

Name	Description	Type	Required
achievement	The unique URL of the achievement you wish to delete.	string	yes

Response

Description	Type
true or error depending on whether the delete was successful.	boolean

Error Code	Description
3404	If the app tries to delete an achievement that the user doesn't have.

Next steps

• Showing Achievements aggregation previews in the Auth Dialog