Android Pointers: User-access tokens in the Facebook SDK 3.0

Facebook offers developers a great way to personalize user experience with the rich data we expose through our API. To keep this information secure, and to ensure that our users know exactly what they’re sharing and with whom, most API calls must be signed with an access token. Each access token identifies your app, the current user, the permissions they’ve granted your app, and the token’s own expiration date.

You’ll also need a new token if:
1. You change the permissions you require from your user
2. The token expires
3. The user changes his or her Facebook password
4. The user logs out of Facebook
5. The user de-authorizes your app on facebook.com

The Facebook SDK 3.0 for Android includes abstractions that remove the need to interact with access tokens directly. This article will walk you through how to manage access tokens through these classes, and how to handle the scenarios above. This SDK is also designed to be backward-compatible, so if you’ve set up access-token refreshing in an existing app, it will continue to work.

Access tokens and the session object
The Facebook for Android SDK 3.0 uses a new class, Session, to authenticate a user and manage that user’s session with Facebook. API calls to Facebook will not use an access token directly; instead, you pass in a Session object that has an associated access token. Session automatically refreshes this token if needed. If you need a new token for any of the five reasons listed above, Session will automatically take your user through the authorization flow again. Note that this is a change from previous versions of the SDK.

The pre-built LoginButton and LoginFragment classes in the SDK provide an additional layer of abstraction, and handle the creation and update of the Session object for you. If you need to create a Session yourself, you can construct it like this:

Session session = new Session(context);

When the Session is created, it attempts to initialize itself from a TokenCache. If the cache exists and has a valid token, the session will be created using that token. If none exists, or if the token has expired, the Session object will create a TokenCache with an empty AccessToken object that has no associated permissions. You do not need to do anything for this to happen.

Instances of Session have a state machine that controls their life cycle and can take the following states: CREATED, CREATED_TOKEN_LOADED, OPENING, OPENED, OPENED_TOKEN_UPDATED, CLOSED, and CLOSED_LOGIN_FAILED. They provide state change notification via a callback interface, StatusCallback. If your Activity extends FacebookActivity, you can also use the more general onSessionStateChange() method to observe changes in session state.

When you create a Session with a valid cached access token, it will be in the CREATED_TOKEN_LOADED state. If there was no access token, or the token had expired, your session will be in the CREATED state.

To make any API call, your session must be OPEN. Opening a session is the same as logging a user into Facebook.

You can open the session immediately and start making API calls without any user interaction if your session is in the CREATED_TOKEN_LOADED state (see open(), openForRead(), or openForPublish(). If your session is in the CREATED state, calling one of the open() functions will prompt your user to log in to Facebook, and you will have to handle cases where login fails.

When you ask a user to log in with Facebook, you can request certain permissions to their data. Facebook makes these as granular as possible so users understand what they’re sharing with your app. You can learn more about what permissions are available to apps in the permissions reference.

We now require that apps ask only for read permissions at first, and delay requesting publish permissions until the first time the app actually publishes to a user’s timeline. This improves user trust and increases the likelihood that users will grant publish permissions to your app. That means that you should begin by calling openForRead() to open your session with read permissions, then request publish or other extended permissions afterward.

The openForRead() method in the Session class takes a Session.OpenRequest object as a parameter. The OpenRequest object takes in the permissions you want from your users using the setPermissions() method. You should also define a callback to notify you when the request has completed, so you don’t attempt any illegal operations.

When openForRead() is called, your user will be prompted to log in with Facebook. If Facebook Login is enabled, and the user is logged into their Facebook for Android app, they will be taken straight to a screen that lists the permissions you are requesting. Once this method completes, your session will be in the OPEN state, and you can start making API calls to get data from Facebook.

If you want to request more read permissions, or publish permissions, you will need a new access token. To get this access token, you should call reauthorizeForRead() or reauthorizeForPublish(). These methods will prompt your user to authorize only the permissions beyond those they have already allowed for your app. There is an example of how to use this method in the publishing to feed how-to.

We hope the tools we have provided in the Facebook for Android SDK 3.0 have made session management and access-token handling as easy as possible. If you have feedback on how we can make it better, please join the Facebook SDK 3.0 Beta Feedback group and let us know!