Gaming Graph Domain (graph.fb.gg)
Gaming graph domain is a separate domain from main graph domain (graph.facebook.com) to host a set of graph APIs specifically designed for gaming apps on Facebook. It’s accessible using graph.fb.gg as the domain address. Read more about using Facebook Graph APIs.
How to enable Gaming Graph Domain?
Your application needs to enroll in Gaming Services to access features in this document. Follow the instructions to enroll your application. When gaming graph domain is enabled, your application will use Facebook Login for Gaming, and receive access token that can access the graph APIs hosted on gaming graph domain using graph.fb.gg as domain address.
Note: For the same application, only one graph domain can be accessed. If your application is enabled for gaming graph domain, it will not be able to access graph.facebook.com, and vise versa.
Graph API Version
Gaming graph domain supports the same range of graph API versions with graph.facebook.com. The same guideline applies regarding the minimum graph API version that each application can access.
Requestable Permissions
Currently supported permissions for Facebook Login for Gaming are:
| Permission | Granted Access | Required/Optional | Need App Review |
|---|---|---|---|
| User's player name and avatar. This replaces | Required | No |
| User's first name and profile picture. | Optional | No |
| User's email address. | Optional | No |
| User's Facebook friends who play the same game and granted this permission. | Optional | Yes |
Any other permission requested will be ignored and returned as denied.
Sample Requests
Getting player name of current user:
GET graph.fb.gg/v7.0/me?field=name
Getting avatar of current user:
GET graph.fb.gg/v7.0/me/picture
Getting current user’s granted permissions:
GET graph.fb.gg/v7.0/me/permissions
Access Token
An access token is an opaque string that identifies a user or app. When someone connects with an app using Facebook Login for Gaming and approves the request for permissions, the app obtains an access token that provides temporary, secure access to graph APIs. Read more about different types of access token.
Gaming graph domain supports using both user access token and app access token. Note certain graph APIs will expect user access token or app token, while others graph APIs will accept both. Please refer to the documentation of each graph API to check which type of access token should be supplied in the request.
User Access Token
User access token for gaming graph domain are generated as response of Facebook Login for Gaming, which needs to be attached to request for accessing graph APIs on the gaming graph domain. Similar to graph.facebook.com, the user access token generated by gaming graph domain could be short-lived or long-lived.
One noticeable difference between token generated for gaming domain (graph.fb.gg) as opposed to graph.facebook.com is that, the gaming domain access token will always start with ‘GG’ as prefix. This is useful for checking if you are receiving a token for gaming graph domain or not.
This token can only be used to access graph.fb.gg only, where using this token on graph.facebook.com will result in OAuth “Token not valid” exception.
App Token
User access token for gaming graph domain can be requested using a few different ways.
- Using Graph API Explorer, as detailed below.
- Using access_token graph API, with details instructions here.
- Compose the token using app secret following this format:
GG|{your-app_id}|{your-app_secret}Debug Access Token
There are two useful ways to debug a token generated for gaming graph domain to gain insights and verify its validity.
- Graph API Token Debugger is a useful tool for analyzing a given access token. Simply paste the token in the tool, and you can verify a few key information from the token debug info:
- Domain should be ‘gaming’.
- Scopes should have ‘gaming_profile’, and other permissions user have granted.
- Expiration time should be a time in future (otherwise token is expired)
- debug_token Graph API can also be used for validating token programmatically using a server-to-server call.
Testing Gaming Graph Domain
We provide the following ways for developers to test the access to gaming graph domain and prepare their applications for gaming graph domain.
Using Graph API Explorer
Graph API Explorer is the most comprehensive tool for testing access to gaming graph domain and all the graph APIs it hosts. Read more about how to use Graph API Explorer.
When your application is enabled for gaming graph domain, an access token will be received for accessing gaming graph domain, and can be validated by checking the prefix of ‘GG’. The graph domain used by graph API explorer will also be automatically switched to graph.fb.gg when such token is provided.
Using Access Token Tool
Access Token Tool is another utility for developers to generate user access or app tokens for testing purposes. If your application has been enabled for gaming graph domain, this tool will automatically generate tokens for gaming graph domain correspondingly.
Prepare Your Application for Gaming Graph Domain
For application developers, below are the instructions for preparing your application for gaming graph domain.
Using Facebook SDK
On client side, it’s highly recommended to use Facebook SDK which handles supporting the gaming graph domain without any change in client code needed. Using a compatible Facebook SDK, the client will make graph API calls to the correct domain (graph.fb.gg vs graph.facebook.com) based on token received. The minimal SDK requirement for different platform are as follows:
- iOS: v6.4
- Android: v6.4
- Unity 3D: v7.19.2
Manually Implementing Support for Gaming Graph Domain
Developers can also manually implement the support for gaming graph domain, as part of integrating with Facebook Login for Gaming, both on client and server side using following methodology:
- If your application is enabled for gaming graph domain, you can expect the following response when user connects your app with Facebook Login for Gaming:
- A user access token that starts with ‘GG’ as prefix
- If signed_requested is requested as response, there will be a ‘graph_domain’ field in the response and will be ‘gaming’.
- You should update the code for making graph APIs in your application so that when getting a user access token for gaming graph domain, it should be using graph.fb.gg as the domain for calling graph APIs, and vice versa. This change is needed both on client and server side.
An application enabled for gaming graph domain can only access graph APIs hosted on gaming graph domain, and will not be able to access graph.facebook.com (an OAuth exception will be thrown).
Migrating to Gaming Graph Domain
For an application that has integrated with Facebook Login and using graph APIs on graph.facebook.com domain today, migration to gaming graph domain is possible. Please work with your Facebook support contact to enable gaming graph domain on your existing application.
To make sure your application will continue to function after migrating to gaming graph domain, please follow the instructions in Prepare Your Application for Gaming Domain section above. You need to make those changes before enabling the migration to gaming graph domain.
User Experience for Existing Users
If your app has previously logged in gamers using the graph.facebook.com domain, those gamers will see the following user experience after your app migrates to the graph.fb.gg domain:
- Gamers that still have a valid token from Facebook Login will remain logged in and that token will continue to be valid for calling the Graph API in the graph.facebook.com domain. However, that token cannot be extended and will expire at the end of its current lifetime.
- When the Facebook Login token expires gamers must reconnect their account using Facebook Login for Gaming and receive a new token for the graph.fb.gg domain. Reauthentication is automatic if your app is integrated with the Facebook SDK. This new token can be extended as long as the gamer continues to use your app.
- Gamers that are using a token in the graph.facebook.com domain cannot access profile data for friends that are using a token in the graph.fb.gg domain. If your app encounters this situation, use the new
gaming_nameandgaming_picturefields instead to retrieve the friends' profile information. - New gamers will connect their account using Facebook Login for Gaming and receive a new token for the graph.fb.gg domain. This new token can be extended as long as the gamer continues to use your app.