Facebook Platform Upgrade Guide
This guide helps you upgrade your apps across versions. It lists deprecations, updates, and the steps you should take to test and prepare your app for a migration or new version. For changes in each platform release see our platform changelog.
Upgrading from v2.3 to v2.4
Graph API
Changing the way fields are retrieved
In the past, responses from Graph API calls returned a set of default fields. In order to reduce payload size and improve latency on mobile networks we have reduced the number of default fields returned for most Graph API calls. In v2.4 you will need to declaratively list the response fields for your calls.
Changes to the way Timeline Posts are retrieved
If your app references the {id}/links or {id}/statuses for Users or Pages, you will need to modify these calls to use {id}/feed.
Maximum Limit of 100 Results on Specific Page Edges
When making a call to a Page and retrieving data, v2.4 imposes a maximum limit of 100 results. This will impact the /feed
, /posts
, and /promotable_posts
edges on Pages. If you expect your Graph API call to exceed this limit you will need to page through the results.
Page Permissions Changes
There are a number of Page permissions changes between v2.3 and v2.4 that your apps will need to account for. Notably, a Page access token is now required to interface with /v2.4/{page_id}/promotable_posts
, /v2.4/{page_id}/offers
, and /v2.4/{page_id}/milestones
. Additionally, Page Milestones and Offers now require manage_pages
and publish_pages
permissions.
Events Changes
In Graph API v2.4 we've removed GET
operations on {event_id}/invited
, {event_id}/likes
, and {event_id}/sharedposts
.
Other Deprecations
There are a handful of features and permission deprecations that are set to 90 day and 2 year schedules. See Platform v2.4 Changelog, 90 Day Deprecations for more details.
Upgrading from v2.2 to v2.3
Graph API
Real Time Updates for Pages
In the past, Real-Time Updates (RTUs) from Pages only contained the ID of the object that triggered the update. This required you to make an additional call to Graph API to discover more context about the update using the {object_id}
. As of March 25, 2015 Page RTUs include the actual content based on the object type which eliminates the need for an additional call.
We also added a new RTU
property for Ratings on Pages. Developers can now subscribe to this property to get an update each time a Rating update occurs.
Default Limit of 25 Results
If you make a call to an edge without providing a limit parameter, v2.3 imposes a default limit of 25 results. If you expect your Graph API call to exceed this limit, include the limit
parameter for a larger response count.
Empty Array Responses
In v2.3 all Graph API responses now serialize empty arrays in valid JSON format. If your code relies on the old way of handling empty arrays see the changelog entry for more details Facebook Platform Changelog, API version 2.3.
Manually Build a Login Flow
If you build your own Login flow, there is an update to the OAuth code exchange that now conforms to the latest OAuth RFC spec. See details in the changelog entry, see Facebook Platform Changelog, API version 2.3.
Picture Edge Default Changes
We changed the behavior of picture edges on Nodes that don't support the picture edge. Prior to Graph API v2.3 this edge returned an question mark image representing an undefined picture.
For this edge on Link
, Post
, Thread
, Comment
, and Status
nodes the Graph API now returns an error.
Request Objects Rename
Previous versions of Graph API supported all app types that made calls to/v2.x/{user-id}/apprequests
. The intended use for this edge is for invite requests for Game apps. Starting with v2.3, if your app makes use of the Requests
object but is not a game you should modify your app to use App Invites.
Page Object Related Changes
Page Access Tokens Required - If your app performs operations on behalf of a Page, such as posts, comments, and likes, these are now made in the context of the passed access token. If you make actions on behalf of a Page, check that your code passes the respective Page access token.
country
Renamedcountries
- We renamed thefeed_targeting
field'scountry
subfield on a Page post tocountries
. This impacts calls toPOST|GET /v2.3/{page-post-id}
.Deleting Pages - If your app deletes Page posts with
DELETE /v2.3/{comment-id}
you now need to pass a Page access token with admin permissions of the page.country
Requirement - If your app updates thelocation
field of a/v2.3/{page-id}
you must include acountry
sub-parameter. If yourcountry='United States'
you also need to include astate
sub-parameter.POST
Changes for Page Fields -POST
updates on thePage
fieldshours
,parking
, orpayment_options
now behave differently. See Facebook Platform Changelog, API version 2.3.
Permission Changes
user_posts
- We added a new permissionuser_posts
that enables apps to access posts on a person's timeline. Previously you could access this content through theread_stream
permission. If your app hadread_stream
permission it has been automatically granted theuser_posts
permission. See Facebook Platform Changelog, API version 2.3.Publishing Posts for Pages - If your app publishes posts for a Page you now need both the
publish_pages
andmanage_pages
permissions. If a user had granted thepublish_actions
andmanage_pages
permissions in v2.2 or below, we have automatically granted that userpublish_pages
. However, to usepublish_pages
or to request it from new users in v2.3 and up, you must have been approved to use that permission via Login Review.read_friendlists
Renamed - We renamd theread_friendlists
permission toread_custom_friendlists
. See Facebook Platform Changelog, API version 2.3. You'll need to specifyread_custom_friendlists
in the Login Dialog from v2.3 onwards. For people who grantedread_friendlists
in previous versions, this will be returned asread_custom_friendlists
when calling/me/permissions
in v2.3 and up.
Location and Place Changes
Consistent
place
Field - If your app usesPlace
tags inPhotos
,Albums
,Videos
, andStatuses
you need to make a few changes to migrate to Graph API v2.3. In v2.3 so theplace
field always contains consistent data including thename
field and alocation
object.Event
andplace
- We updated theEvent
node to store Place data more consistently. Before an event'slocation
field contained thename
of the place, and thevenue
field contained thelocation
object. In v2.3 bothlocation
andvenue
fields are deprecated; we store thename
andlocation
object in theplace
field.
Other 90 Day Deprecations
There are a numbers of features and Social Plugins that are deprecated in 90 days. See Platform v2.3 Changelog, 90 Day Deprecations.
Social Plugins
Comments Plugin Changes - If you use the Facebook Comments Plugin, upgrade your Facebook JS SDK url to pass the version parameter
version=v2.3
. After June 22, 2015, we will automatically upgrade older versions of the Comments Plugin to v2.3.Facebook Like Box - If you use the Facebook Like Box, we recommend you use the Page Plugin instead. To do this, replace the
div class
of your Facebook Like Boxdiv=fb-like-box
withdiv=fb-page
and it upgrades automatically.
Upgrading from v2.1 to v2.2
Graph API
Real Time Updates for Pages
Many apps get real time updates for changes to pages. These include comments, posts and other data. In versions previous to v2.2, this was done by adding an app to the /{page-id}/tabs
app that wasn't registered as a page tab app.
We're deprecating using the tabs
edge to register your app for real time updates. Instead of using the tabs
edge, you can use the new /v2.2/{page-id}/subscribed_apps
endpoint to manage subscriptions to real time updates.
All apps are now required to use the new real-time updates interfaces.
Page Access Tokens Now Required on Many Interfaces
In previous versions it was possible to use a User Access Token to access some page data through some interfaces. In v2.2, many interfaces now require use of a Page Access Token. Please see the various entries listed in the changelog for details.
Limit of 50 IDs Returned With ids=x,y,z
Syntax
If you're using the ids=
syntax, covered in our Using the Graph API doc, you are now limited to requesting only 50 IDs at a time.
The /{page_id}/admins
Edge is Now /{page_id}/roles
In addition to moving the interface to a new edge name, the values returned are different. Please see the changelog for more details.
/{page_id}/settings
Uses a New Format For Updates
Previous versions used the setting
and value
params. In v2.2, you should specify the option
param which should be an object containing a single key/value pair with the setting enum as the key. Please see the settings
edge for details.
/{group-id}/albums
Now Uses the Same Syntax as /{user_id}/albums
Previous versions of the albums
edge on groups had a different format than the edge on users. They now use the same format. Please see the /{user-id}/albums
edge for more information.
Other 90 Day Deprecations
Several other rarely used features are being deprecated in 90 days. Please see that section of the changelog for more information.
Upgrading from v2.0 to v2.1
Graph API
FQL is no longer available
FQL has been removed in v2.1, and can no longer by queried either directly, or via the Graph API.
App Insights endpoint has been moved and functionality changed
v2.1 includes access to the new App Insights data via a new /app_insights
edge. This replaces the previous /insights
edge on the App node. Apps using this edge should migrate to the new edge, and check the updated list of metrics and parameters.
New Field Expansion format for Making Nested Requests
A new, more compact syntax has been introduced for making nested API requests. The old syntax is still available in v2.1, but apps should switch to using the new format as soon as possible.
Queries to graph.facebook.com/?id={url}
replaced by new URL node
There was previously a Graph API endpoint graph.facebook.com/?id={url}
available that allowed apps to retrieve Open Graph objects, App Links, or share metrics that were associated with a particular URL. In v2.1, these must instead be retrieved via the new URL node.
API Response Changes
All API endpoints will now always return valid JSON. Many API calls before v2.1 returned plain text true
or a raw int like 378293782
as the response. With v2.1, those calls will now return valid JSON, such as:
{
“success”: true
}
This will affect any API endpoints that previously returned something that was not valid JSON - typically this is mostly only publishing or deleting endpoints.
Consult the reference docs for Graph API to see if any endpoints that you use have changed response formats.
installed
permission no longer exists
The /me/permissions
edge previously returned an installed
pseudo-permission that would indicate that someone had installed an app. In v2.1 this permission has been removed, and instead apps should assume that when /me/permissions
returns any data
(and not an error) that the user has installed the app.
uri
no longer a valid field on profile pictures
Apps previously requesting uri
should instead use url
.
/v2.1/{post-id}
will now return all photos attached to the post
In previous versions of the API, only the first photo was available via the picture
field of a post. Now, apps will be able to request all the photos attached to a post via the attachments
field.
REST API
The previously deprecated REST API has been completely removed in v2.1, and all apps still using it must migrate to using Graph API.
If your mobile app is using the undocumented auth.ExtendSSOAccessToken
endpoint from the REST API to extend long-lived access tokens, you need to upgrade your app to use the full iOS or Android SDK. The SDKs will automatically handle extending access tokens.
Defaulting to Graph API v2.0
On April 30, 2015, we began migrating all apps to Graph API v2.0. You should test all possible features to make sure everything works.
If your app is not fully functional:
Your app may be requesting permissions it hasn't been approved to use. To request permissions other than
public_profile
,user_friends
andemail
, you'll need to submit for Login ReviewYour app may be using features that were deprecated or updated in v2.0. For the full list of changes, please see Graph API v2.0 Changelog.
Opting Out
Prior to this migration, some apps had the option to force Admins, Developers, and Testers to use Graph API v2.0. If your app hasn't yet been migrated yet, you'll still see this option in the Migrations tab of your app's Settings page:
![](http://web.archive.org./web/20150907015242im_/https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-xfa1/t39.2178-6/10935987_940906285950099_1850462299_n.png)
On April 30th, 2015, the Default Admins, Developers, and Testers to Graph API v2.0 setting was turned ON. You can turn it on and off as you continue testing your app.
Once your app is migrated, this option will disappear and you will no longer be able to call v1.x of the Graph API. Your app developers and users will see v2.0 behavior.
Related Resources
For more information on Graph API v.2.0 and the new login, see:
Upgrading from v1.0 to v2.0
Implementing Versions in your Apps
The largest change is the introduction of API versioning. Many services that Facebook offer are now versioned, such as:
- The behavior and content of certain Graph API endpoints
- What permissions are available and what your app can see when they are granted
- The behavior of dialogs.
We'll introduce new versions of the API whenever we make a breaking change an existing API. APIs are supported for at least two years after they're introduced. Multiple versions of the API will be in service at the same time. We strongly encourage you to upgrade when new versions are introduced, but it's not required.
On April 30, 2015, we deprecated API v1.0 and defaulted all v1.0 apps to calling v2.0. Version 2.0 supported for at least two years. At the earliest, it will expire on April 30th, 2016.
You can choose which version of the API you want to use by:
- Initializing the JavaScript SDK with the version you want to use and then making calls through
FB.api()
, which will automatically route API calls to the versioned endpoint you choose. - Integrating the Facebook SDKs for iOS or Android, which are set up to call the latest version of the API that was available on the day the SDK was released.
- For people making manual calls to our API without an SDK, the version is picked by putting the version in the path when you make an API call (such as
graph.facebook.com/v2.0/me
).
When a version of the API expires, apps that still use the expired version will automatically start using the oldest supported version of the API.
Upgrading Web Apps (JavaScript)
If your web app is built on top of Facebook's JavaScript SDK, you will need to make at least the following two changes:
- Update the path to the SDK
- Tell the SDK which version of the API you want to use
Change the path to the JavaScript SDK:
We've changed the location of the SDK to support new features. If you were including the old version of the SDK via a path:
js.src = "//connect.facebook.net/en_US/all.js";
You should update it to:
js.src = "//connect.facebook.net/en_US/sdk.js";
Add the version you want to your FB.init()
call:
If you're using FB.init()
from the JS SDK, you need to add a new version
parameter to the call, like this:
FB.init({
appId : '{app-id}',
version : 'v2.0'
});
Update the code snippets for your social plugins includes:
If you're updating to support versions, you should go to the social plugin you're using and get a new code snippet to use on your site. If your snippet is older, it may not have the right callback setup to support versioning during initialization.
Following is an example of an updated version of a Like button. Please visit the appropriate social plugin page and re-generate the code for your site.
<script>(function(d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); js.id = id;
js.src = "//connect.facebook.net/en_US/sdk.js#version=v2.0&xfbml=1&appId=113263196637420";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
<div
class="fb-like"
data-href="https://developers.facebook.com/docs/plugins/"
data-layout="standard"
data-action="like"
data-show-faces="true"
data-share="true">
</div>
Once you've done this, all calls made through the SDK will automatically have the version prepended. For example, the call FB.api('/me', ...);
will actually be sent to /v2.0/me
. The same is true for dialogs you invoke, such as the Login Dialog - you will get the v2.0 version of the dialog.
Upgrading Web Apps (PHP)
If your web app is built in PHP and you're using an old version Facebook SDK for PHP (3.x
), you should upgrade to the latest PHP SDK (version 4.x
).
Upgrade Workaround
While we strongly recommend to upgrade to the new PHP SDK, we understand that such an upgrade can take some time. To keep your app running while you work on your upgrade, you can apply the patch posted below to the Facebook SDK for PHP version 3.x
.
Login URL Patch
In the file base_facebook.php
update the method getLoginUrl()
to the following:
// File: facebook-php-sdk-master/src/base_facebook.php
public function getLoginUrl($params=array(), $version) {
$this->establishCSRFTokenState();
$currentUrl = $this->getCurrentUrl();
// if 'scope' is passed as an array, convert to comma separated list
$scopeParams = isset($params['scope']) ? $params['scope'] : null;
if ($scopeParams && is_array($scopeParams)) {
$params['scope'] = implode(',', $scopeParams);
}
return $this->getUrl(
'www',
$version . '/dialog/oauth',
array_merge(
array(
'client_id' => $this->getAppId(),
'redirect_uri' => $currentUrl, // possibly overwritten
'state' => $this->state,
'sdk' => 'php-sdk-'.self::VERSION
),
$params
));
}
This patch is adding a $version
parameter to the method getLoginUrl()
. You can now specify a version when you create your login URL:
$loginUrl = $facebook->getLoginUrl(array(), 'v2.0');
This will cause to show the new login dialog.
API Calls
All calls made through the PHP SDK will automatically have the version prepended. For example, the call $facebook->api('/me', ...);
will actually be sent to /v2.0/me
.
You can can control the version of your API calls by manually prepend the API version to the path argument:
$facebook->api('/v2.0/me', ...);
Upgrade to PHP SDK v4.x
As the version 4.x
of the Facebook SDK for PHP is a following a different structural appraoch there is no simple upgrade guide from version 3.x
to version 4.x
. Please follow our Getting Started Guide for the Facebook SDK for PHP (version 4.0.0
) to get familiar with the new SDK.
Upgrading iOS Apps
The Facebook iOS SDK is automatically pinned to the most recent version of the API when the SDK is released. It will automatically add the version number to any API calls you make. Upgrading the version of the SDK you're using will automatically update the version of the underlying API that's used.
For example, the following code that uses the [FBRequestConnection startWithGraphPath:completionHandler:]
method will automatically call /v2.0/me
on your behalf:
[FBRequestConnection
startWithGraphPath:@"me/events?fields=cover,name,start_time"
completionHandler:
^(FBRequestConnection *connection,
id result,
NSError *error) {
(...)
}
];
It's possible to override the version that's called by using the [FBRequest overrideVersionPartWith:]
method.
Please see the upgrade instructions for the iOS SDK for more information.
Upgrading Android Apps
The Facebook Android SDK is automatically pinned to the most recent version of the API when the SDK is released. It will automatically add the version number to any API calls you make. Upgrading the version of the SDK you're using will automatically update the version of the underlying API that's used.
For example, the following code will automatically call /v2.0/me
on your behalf:
Request request = new Request(session, "me/events?fields=cover,name,start_time");
request.executeAsync();
You can override the version of the call with Request.setVersion().
Please see the upgrade instructions for the Android SDK for more information.
Invoking different API versions manually
If you're not using one of Facebook's SDKs, then you'll need to build version URLs manually. You choose which version of the API to call by prepending the verison to the graph API call. For example, the /me
endpoint in version 1.0 is called without any version number:
curl https://graph.facebook.com/me?access_token={valid-token}
Upgrading to version 2.0 is as simple as adding v2.0
to the front of the path:
curl https://graph.facebook.com/v2.0/me?access_token={valid-token}
This works for more than just the Graph API endpoints. It also works with dialogs that you launch in your app. For example, if you're manually invoking the login dialog for Facebook Login, you can invoke v2.0 of the dialog by using the following call:
https://www.facebook.com/v2.0/dialog/oauth?
client_id={app-id}
&redirect_uri={redirect-uri}
User IDs and Friends
Graph API v2.0 includes some changes to how user IDs and friends work in order to better protect people's info. This includes several changes:
1. App-scoped User IDs
Facebook will begin to issue app-scoped user IDs when people first log into an instance of your app coded against v2.0 of the API. With app-scoped IDs, the ID for the same user will be different between apps.
No matter what version they originally used to sign up for your app, the ID will remain the same for people who have already logged into your app. This change is backwards-compatible for anyone who has logged into your app at any point in the past.
If you're not mapping IDs across apps, then no code changes should be required. If you need to map the same user IDs across multiple apps or run cross-app promotions, we've added a new API called the Business Mapping API. This lets you map a logged-in user's IDs across apps as long as those apps are all owned by the same business. Learn more about implementing cross-promotions.
For users who have not logged into your app, the user ID may change depending on the version of the API that you call. In v1.0 of the API users who have not logged into your app will be referred to by their original Facebook user ID, whereas in v2.0 they will be referred to by an app-scoped ID.
We've added new API endpoints that allow you to tag and invite friends who don't use your app. These APIs return tokens which may be used to generate custom interfaces for tagging and invitations. Those tokens aren't meant to be cachable and we make no guarantees that they will be stable beyond 24 hours from the time the API response containing them was received. They aren't the same as either the IDs used on data for people not logged into your app nor the same as the app-scoped IDs.
Users can check their app-scoped IDs for each app they've installed in the app's Edit Settings dialog. Make sure users of your app know how to find it when they contact you with support queries.
2. Friends now has a new permission
In v1.0 and earlier, the list of friends was available as part of the default permission set. To give people more control about the info they share with apps, we've separated the list of friends from the default. We have added a new permission so that you can ask for the list of friends. That permission is called user_friends
. In order to use user_friends
, you will need to add it to the list of scopes in your app when requesting permissions.
This offers you a new opportunity: you don't have to ask for the list of friends until a person using your app is ready to use your app socially. You can ask for this permission later in your app's login flow.
3. /me/friends
returns the user's friends who are also using your app
In v2.0, the friends API endpoint returns the list of a person's friends who are also using your app. In v1.0, the response included all of a person's friends.
There are two key use cases where apps need access to non-app friends: tagging and inviting. In v2.0, we've added the Taggable Friends API and the Invitable Friends API to support these flows.
After a person has logged in with v2.0 of Facebook Login, calling /v1.0/me/friends
and /v2.0/me/friends
will both result in the v2.0 behaviour - both calls will return the set of the person's friends who also use the app.
4. All friend_*
permissions have been removed
In v1.0, it was possible to ask for permissions that would allow an app to see a limited amount of friend data, such as a person's friend's likes, their birthdays, and so on.
In v2.0, those permissions have all been removed. It's no longer possible for an app to see data from a person's friends unless those friends have also logged into the app and granted permission for the app to see it that data.
5. Friend lists are now title-only
In API v2.0 the list of friends within a friend list is no longer available, and the manage_friendlist
permission has been deprecated.
In v2.0, you can use friend lists to build a custom audience selector for making posts to Facebook. For example, limiting a post to 'Friends', 'Co-workers' or 'Old College Friends'.
Login
Facebook Login in v2.0 contains significant differences as compared with the previous version. At a high level, these changes include:
- Permissions are now optional for people using your app. The Login Dialog now lets people choose what info they share with your app. People can disable what they share on a permission-by-permission basis.
- The list of friends is no longer part of the default list of permissions and only returns the friends using the app. See the section above on user IDs and friends to learn more about how IDs and friends are changing.
basic_info
has been replaced bypublic_profile
. The default permission set calledbasic_info
has been replaced bypublic_profile
. The permission set is the same, aside from the fact that list of friends has been moved to a separate permission.- There have been significant changes to permissions. Most notably, all of the
friends_*
permissions have been removed. Two new permissions have been added as well. Please see the section below on permissions for more information. - We now review some apps using Facebook Login. If your app is asking for more than
public_profile
,email
anduser_friends
we now require your use of those permission to be reviewed by Facebook before those permissions can be requested from regular users. Please see our section below on review for more information.
Optional Permissions
People can decline any permission that your app requests in the login flow. This is done during the login process, via the Facebook Login Dialog. The only required permission is public_profile
, which people must share as part of logging in with Facebook. All other permissions can be declined.
![](http://web.archive.org./web/20150907015242im_/https://fbcdn-dragon-a.akamaihd.net/hphotos-ak-xfa1/t39.2178-6/10173501_712654372111832_803467338_n.png)
Figuring out which permissions have been declined
Because a person can decline certain permissions, it's important that you check which permissions the user granted once they have logged into your app.
On the web, the easiest way to figure out which permissions have been granted is to make a call to the /me/permissions
endpoint. That endpoint lists all the permissions that your app has been granted as well as the permission which were declined.
On iOS, we've added a new property called [FBSession declinedPermissions]
which returns the list of permissions that has been declined.
Android has a new method called Session.getDeclinedPermissions()
which returns a list of the declined permissions.
Re-asking for Declined Permissions
It's always been possible to ask for additional permissions when they are appropriate in your app's flow. However, the new Login Dialog lets people decline to share data with your app even if your app has requested it. By default, the Login Dialog won't let you re-request permissions that someone has explicitly declined. Your app must re-ask for declined permissions with special handling.
Web apps must explicitly pass a new option to the Login Dialog: auth_type: rerequest
. Details on how the new option works on the web is covered in our documentation on using the JavaScript SDK on the Web.
The iOS SDK doesn't need a new flag, but you must use [FBSDKLoginManager logInWithPublishPermissions]
and [FBSDKLoginManager logInWithReadPermissions]
with the full list of permissions your app needs to trigger re-asking for permissions.
Android is similar, except the function is LoginManager.logInWithReadPermissions
and LoginManager.logInWithPublishPermissions
.
Permissions Changes
In v2.0 of Facebook Login we've made some changes to permissions that will require that you audit your app. These include:
- In v2.0, access to
/me/friends
is no longer part of the default permissions. We now require you to explicitly request the new permissionuser_friends
from users. - The permission
read_friendlists
no longer allows you to read the list of friends in a friend list, but only lets you access the name of the list. - The permission
basic_info
has been replaced bypublic_profile
. - We've added a new permission called
user_tagged_places
. This gives access to a new endpoint,/me/tagged_places
which replaces the/me/locations
endpoint.
Along with the above changes and additions, this is the full list of permissions that have been removed from v2.0. Your app should not ask for any of the following:
create_event
manage_friendlists
read_requests
user_checkins
user_notes
user_online_presence
user_questions
user_subscriptions
xmpp_login
friends_about_me
friends_actions.books
friends_actions.fitness
friends_actions.music
friends_actions.news
friends_actions.video
friends_actions:APP_NAMESPACE
friends_activities
friends_birthday
friends_checkins
friends_education_history
friends_events
friends_games_activity
friends_groups
friends_hometown
friends_interests
friends_likes
friends_location
friends_notes
friends_online_presence
friends_photos
friends_questions
friends_relationships
friends_relationship_details
friends_religion_politics
friends_status
friends_subscriptions
friends_videos
friends_website
friends_work_history
Login Review
As part of the new Facebook Login, apps that ask for more than public_profile
, email
and user_friends
need to be reviewed by Facebook.
- Active apps created before April 30th 2014 must be reviewed by April 30th 2015. After that date, unapproved permissions will not be shown to regular users.
- All apps created on or after April 30th 2014 must be reviewed before they can request additional permissions from regulary users.
The review process is covered in our review guide for login.
Friend Interactions Between v1.0 and v2.0 Logins
If you've used Facebook Login in your app in the past, you've got some people using your app that logged in with v1.0. Once you update, new people (and people logging into their old accounts) will be using v2.0. v2.0 has different expectations and terms compared to v1.0.
Between v1.0 and v2.0, we've made it possible for someone to not share their list of friends, even if your app asks for access. This might not seem like a problem at first, but it's important to point out that this means that they don't want to share who they are friends with in your app. So denying access to the friend list doesn't just apply to the person logging in, but also applies to that person's friends.
It's best to describe this with an example.
- Person A and Person B are friends on Facebook.
- Person A logs into your app with v1.0, before v2.0 was introduced. Because this is v1.0, their full friend list is shared with your app. Person B is visible in Person A's friend list, even though Person B doesn't yet use the app. This is standard v1.0 behaviour.
- Person B logs into a instance of your app which has been upgraded to use Graph API v2.0. Person B decides they don't want to share their friend list with your app and declines the
user_friends
permission. Your app will not be able to see Person B's list of friends. i.e. calling/v2.0/USER_B/friends
will return an empty array. - Because Person B declined the
user_friends
permission, they are no longer returned in Person A's friend list.
This behaviour might not seem obvious at first, but it's worth pointing out because it's something your app needs to expect.
Another thing that's worth pointing out: People that signed in with v1.0 still have their complete list of friends visible through the API. However, if you call /me/friends
with v2.0 of the API, you'll only get friends who are also using your app. Calling the newer version of the API will invoke the new behaviour, even if someone first logged into your app using v1.0.
Upgrading Web Apps for Login
Upgrading web apps from v1.0 to v2.0 for Login is relatively easy.
Step 1: Update the Facebook SDK to the new path and add the version flag:
As mentioned in the versioning section you need to change the version number and path when you include the JavaScript SDK:
<!-- In the past this file was called all.js, now, it is called sdk.js -->
<script src="//connect.facebook.net/en_US/sdk.js"></script>
...
FB.init({
appId : '{app-id}',
version : 'v2.0', // Version flag chooses version for the SDK
...
Step 2: Update any paths by adding the version to the path:
If you're building an app by loading the Login Dialog directly, you need to insert 'v2.0' in front of paths that prefix various parts of the login dialog. (People using the JavaScript SDK don't need to do this because it's handled on their behalf.) For example, this:
https://www.facebook.com/dialog/oauth?
client_id={app-id}
&redirect_uri={redirect-uri}
turns into this:
https://www.facebook.com/v2.0/dialog/oauth?
client_id={app-id}
&redirect_uri={redirect-uri}
Step 3: Update your scope parameters to handle changes to permissions:
On the web, the scope
parameter is used to pass permissions, on both our built-in login button, but also as the a parameter to the login dialog.
Please see the section below on permissions for more information on what permissions have changed.
Step 4: Handle any interactions that are new to v2.0:
As covered elsewhere in this document, you need to make sure your app isn't adversely affected by changes to login, graph api or user IDs.
Step 5: Submit your app for review:
If you're asking for more than public_profile
, email
and user_friends
your app must be reviewed by Facebook before anyone other than the developers of the app can use it. Please have a look at our documentation for Login Review for more information.
https://www.facebook.com/v2.0/dialog/oauth?
client_id={app-id}
&redirect_uri={redirect-uri}
Upgrading iOS Apps for Login
Upgrading iOS apps from v1.0 to v2.0 is relatively easy.
Step 1: Integrate the new version of the iOS SDK:
The new iOS SDK is tied to v2.0 of the APIs, so simply updating to the most recent version of the SDK is enough to start using the new APIs and new login dialog. Please see the changelog for the iOS SDK for more information.
Step 2: Update the login view and session for any permissions changes:
Since permissions have changed in v2.0 of the API, you need to audit the code in your iOS app that pertains to permissions. Permissions can be requested via FBLoginView
and FBSession
.
Step 3: Submit your app for review:
If you're asking for more than public_profile
, email
and user_friends
your app must be reviewed by Facebook before anyone other than the developers of the app can use it. Please have a look at our documentation for login review for more information.
Upgrading Android Apps for Login
Upgrading Android apps from v1.0 to v2.0 is relatively easy.
Step 1: Integrate the new version of the Android SDK:
The new Android SDK is tied to v2.0 of the APIs, so simply updating to the most recent version of the SDK is enough to start using the new APIs and new login dialog. Please see the changelog for the Android SDK for more information.
Step 2: Update the login view and session for any permissions changes:
Since permissions have changed in v2.0 of the API, you need to audit the code in your Android app that pertains to permissions. Permissions can be requested via UI elements like the LoginButton
or directly through the LoginManager
.
Step 3: Submit your app for review:
If you're asking for more than public_profile
, email
and user_friends
your app must be reviewed by Facebook before anyone other than the developers of the app can use it. Please have a look at our documentation for login review for more information.
Graph API
Using the Graph API in v2.0 requires following the steps outlined above in the section on versioning. Your SDK may need updates, or you may need to update the paths you use to call into the graph API.
This part of the upgrade guide covers the changes to the graph API endpoints in detail.
Changes
- In v1.0, there were API endpoints that didn't require an access token to call. In v2.0, all calls to endpoints now require an access token, except for calls to get an object's picture.
/me/friends
has undergone significant changes. Please see the section above on user IDs and login for details./me/friendlists
has changed. Please see the changes in the login section for more information.- The
/me/permissions
endpoint changed. See the reference for more information.
New endpoints
/me/taggable_friends
: The new Taggable Friends API. In the past if you wanted to tag friends in a post, you had to get their IDs, names and then pass that information into the post to tag them. With this new API you get a set of tokens that identify friends along with their names and pictures. Using this, it's easy to build a custom tagging interface from your app. If you use this feature, your app will have to go through review before it can tag people in posts or photos. Please note that the tokens returned through this API are not the same as the IDs returned via/me/friends
./me/invitable_friends
The new Invitable Friends API. This new API returns a set of people (represented by tokens, names and pictures) in order for you to build your own custom invites interface. Much like the taggable friends interface, the tokens returned here are not the same as the IDs returned via/me/friends
and should not be re-used or saved. Using this API does not require review, but is only available to Games on Facebook.com./me/tagged_places
: The new Tagged Places API. This API replaces the v1.0/me/locations
endpoint. The oldlocations
endpoint returned an array of posts, checkins or status messages. The new API returns an array of Facebook Places which a user has been tagged at in photos, videos, statuses and links./{object-id}?fields=context
: The new Social Context API. This API surfaces friends' interactions with objects within your app. You can use on on Pages, Apps, Open Graph Objects and Users to surface social context between the calling user and that object./me/ids_for_business
: The new Business Mapping API. In v2.0 of the API, Facebook will begin to issus app-scoped user IDs when new users login to an instance of your app which is coded against v2.0 of the API. For developers who operate multiple apps (i.e. game developers) the Business Mapping API lets them correlate the same user's app-scoped IDs across the multiple apps owned by the same business. A common use case is for cross-app promotion between games.
Removed endpoints
- The
/me/username
field has been removed. /me/locations
has been removed. Please use/me/tagged_places
instead./me/checkins
has been removed, along with theuser_checkins
permission. Please use/me/tagged_places
instead/me/questions
has been removed, along with theuser_questions
permission. This also includes/{page-id}/questions
,/{group-id}/questions
,/{question-id}
and/{question-option-id}
./me/subscribers
and/me/subscribedto
have been removed./me/username
has been removed./me/notes
has been removed./{page-id}/notes
has been removed./{page-id}/questions
has been removed.- Public post search is no longer available. (
/search?type=post&q=foobar
) - News Feed search is no longer available (
/me/home?q=foobar
)
FQL
FQL is still available in version 2.0
, but will not be available in the next version of platform. This early warning is given so that developers can start migrating off FQL to the Graph API as soon as possible.
Sharing
Tagging People
Apps that publish stories on Facebook can tag friends as part of that story. In v2.0, it's no longer possible for an app to see friends who don't use the app, so we're providing a new API called the Taggable Friends API that lets an app get a list of friends, but without their IDs. Instead the API hands back tokens that can be used to tag friends, but aren't useful to store.
Upgrading to the taggable friends API means using these tokens instead of the old user IDs.
Please see our documentation on on the taggable friends endpoint which also contains links to the affected places where you can publish stories.
App links
App Links is an open, cross platform solution for app to app linking. App Links provides all the tools you need to expose deep links in your app or to have your app link out to others in the ecosystem.
You can learn more about the App Links standard at applinks.org and about how to integrate it into your app in our iOS and Android documentation on App Links.
New Share Dialog for Web
We have launched a new Share dialog for web that contains the same ability to share links and status messages as the previous Feed and Share dialogs, but adds the ability to publish Open Graph stories without requiring Facebook Login. The older dialogs will continue to work, but you can switch to the new Share dialog with a simple change to your JavaScript SDK FB.ui()
call, or to the URL you're redirecting to for the dialog. Read our full guide to this new dialog to see the new parameters and method to use.
Legacy Feed and Share Dialog
Any apps using the legacy Feed and Share dialog can no longer use a username in either the to
or from
fields when calling via v2.0.
Feed Dialog Only Accepts Friends Who Use Your App
In v2.0, the feed dialog only accepts the user IDs of friends who also use your app. In the past, you could pass in the IDs of friends who didn't and post stories on their timeline. This is no longer possible.
Games and Payments
In addition to the points below, we have a separate games migration guide which will take you through changes specific to games on the Facebook Platform in greater detail.
Game Groups
Consider using the Create group dialog
You may want to use a client-side dialog that enables players to create group. This is particularly useful on mobile games if you want to call Facebook directly to create a group. This is optional.
Adding users has changed
Apps no longer have the ability to add users to groups via API (except for users who have a role in the app (Admins, Developers, Testers, Test Users). Users are now added to a group by a client-side dialog which exists in the JS, iOS and Android SDKs.
Apps can no longer read a group's feed
Any functionality that requires the app's ability to read a group's feed should be removed from your game.
Create event by API has been removed
Any functionality that requires the app's ability to create an event via API should be removed.
Deleting a group has changed
The logic around deleting a group has changed. Apps can now only delete groups if they have no members. Apps must remove all members from a group before deleting it.
The user_groups
permission is not required
Apps can now query /USER_ID/groups
and it will return the game groups that a user belongs to for that specific app. If you're asking this permission to get a user's groups, you should consider not asking for the permission anymore and modify your logic to take into account that the response only returns apps that belong to your app.
Apps can post as apps
Apps can now post to groups as apps. This is new functionality that you may want to integrate into your app.
Non-app Friends
Invitations and Requests have been changed in v2.0 because the /me/friends
endpoint no longer returns all friends. Please see our games upgrade guide for information on how to use the new Invitable Friends API.
Mapping IDs Across Apps
We're providing a new Business Mapping API that lets you map IDs across apps for the purposes of cross-game promotion. Please see that guide for details on the use case and how to use it.
Questions?
If you have any questions, please check out the FAQs.