Using the Graph API - Android

The Android SDK has support for integrating with Facebook Graph API. With the GraphRequest and GraphResponse classes, you can make requests and get responses in JSON asynchronously. You can also make batch requests with a single round-trip to the Facebook servers with GraphRequestBatch.

Learn more about Graph API in:

See also GraphRequest, GraphResponse and GraphRequestBatch references to learn how to use the Facebook SDK for Android and to make Graph API calls for additional use cases.

Prerequisites

Before you begin, set up:

GraphRequest Class

The GraphRequest class has a newMeRequest method which calls the /user/me endpoint to fetch the user data for the given access token.

Android SDK sends any permissions your app has in the access_token and this controls data access. If your app has no available access token, Graph API returns only publicly available information. For details on User properties and permissions, see Graph API Reference, User.

By default a newMeRequest method fetches default fields from a user object. If you need any additional fields, or want to reduce the response payload for performance reasons, you can add a fields parameter and request specific fields:

GraphRequest request = GraphRequest.newMeRequest(
        accessToken,
        new GraphRequest.GraphJSONObjectCallback() {
            @Override
            public void onCompleted(
                   JSONObject object,
                   GraphResponse response) {
                // Application code
            }
        });
Bundle parameters = new Bundle();
parameters.putString("fields", "id,name,link");
request.setParameters(parameters);
request.executeAsync();

In the callback method, the response data is deserialized into a JSONObject if the request is successful. The fields that can't be fetched due to missing permissions will be omitted from the result.

For the logged in user, the SDK has Profile and ProfileTracker classes, see Facebook Login for Android.

Fetch User Data

The data you access depends on the permissions someone grants your app and data they chose to share with apps. Here's an example Graph API raw response for user_location and user_birthday:

{
  "id": "12345678", 
  "birthday": "1/1/1950", 
  "first_name": "Chris", 
  "gender": "male", 
  "last_name": "Colm", 
  "link": "http://www.facebook.com/12345678", 
  "location": {
    "id": "110843418940484", 
    "name": "Seattle, Washington"
  }, 
  "locale": "en_US", 
  "name": "Chris Colm", 
  "timezone": -8, 
  "updated_time": "2010-01-01T16:40:43+0000", 
  "verified": true
}

Handling Results

Depending on the endpoint you call, you either receive a JSONObject or a JSONArray.

Single object calls such as newMeRequest return a JSONObject. Calls for multiple results such as newMyFriendsRequest return a JSONArray.

Handling Errors

You can examine the error field on a GraphResponse object to see whether or not a request fails. The error field is of type FacebookRequestError. The methods you can call are:

The error object has fields that explain details about the error including:

  • error code,
  • sub error code
  • error message
  • user facing error message
  • And other messages.

For more details about possible error codes, see Using the Graph API, Handling Errors.

The GraphResponse object also has an enum that categorizes the error. The three possible categorizations are:

  • LOGIN_RECOVERABLE - There is an issue that requires the user to log in again. You can call the LoginManager's resolveError with the GraphResponse object and the activity or the fragment from your app app. This triggers the Faceboook Login UI, and you need to implement a CallbackManager by the calling fragment or activity for the login to succeed.
  • TRANSIENT - Indicates that a temporary issue occurred, and your app can retry the request.
  • OTHER - Indicates a general issue ocurred, and you can get more details by examining the error code and sub error code.

Troubleshooting

If you have any issues fetching user data, enable HTTP request logging by adding this code before your app requests user data:

FacebookSdk.addLoggingBehavior(LoggingBehavior.REQUESTS);

This will log details about HTTP requests and response to the console log.

Batch Requests

You should make batch requests for data if your app handles these types of scenarios:

  • Access significant amounts of data in a single request or
  • Make changes to several objects at once.

If you would like to reduce the amount of server round-trips, you can use a bath request. For example we fetch a user and their friends:

GraphRequestBatch batch = new GraphRequestBatch(
        GraphRequest.newMeRequest(
                access_token,
                new GraphRequest.GraphJSONObjectCallback() {
                    @Override
                    public void onCompleted(
                            JSONObject jsonObject,
                            GraphResponse response) {
                        // Application code for user
                    }
                }),
        GraphRequest.newMyFriendsRequest(
                access_token,
                new GraphRequest.GraphJSONArrayCallback() {
                    @Override
                    public void onCompleted(
                            JSONArray jsonArray, 
                            GraphResponse response) {
                        // Application code for users friends 
                    }
                })
);
batch.addCallback(new GraphRequestBatch.Callback() {
    @Override
    public void onBatchCompleted(GraphRequestBatch graphRequests) {
        // Application code for when the batch finishes
    }
});
batch.executeAsync();

The example above shows the batch request as an asynchronous call. If this code is on a background thread, and you'd like to block until the call finishes, you can call batch.executeAndWait().

Related Resources