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 Renamed countries - We renamed the feed_targeting field's country subfield on a Page post to countries. This impacts calls to POST|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 the location field of a /v2.3/{page-id} you must include a country sub-parameter. If your country='United States' you also need to include a state sub-parameter.

  • POST Changes for Page Fields - POST updates on the Page fields hours, parking, or payment_options now behave differently. See Facebook Platform Changelog, API version 2.3.

Permission Changes

  • user_posts - We added a new permission user_posts that enables apps to access posts on a person's timeline. Previously you could access this content through the read_stream permission. If your app had read_stream permission it has been automatically granted the user_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 and manage_pages permissions. If a user had granted the publish_actions and manage_pages permissions in v2.2 or below, we have automatically granted that user publish_pages. However, to use publish_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 the read_friendlists permission to read_custom_friendlists. See Facebook Platform Changelog, API version 2.3. You'll need to specify read_custom_friendlists in the Login Dialog from v2.3 onwards. For people who granted read_friendlists in previous versions, this will be returned as read_custom_friendlists when calling /me/permissions in v2.3 and up.

Location and Place Changes

  • Consistent place Field - If your app uses Place tags in Photos, Albums, Videos, and Statuses you need to make a few changes to migrate to Graph API v2.3. In v2.3 so the place field always contains consistent data including the name field and a location object.

  • Event and place - We updated the Event node to store Place data more consistently. Before an event's location field contained the name of the place, and the venue field contained the location object. In v2.3 both location and venue fields are deprecated; we store the name and location object in the place 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 Box div=fb-like-box with div=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 and email, you'll need to submit for Login Review

  • Your 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:

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 by public_profile. The default permission set called basic_info has been replaced by public_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 and user_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.

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 permission user_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 by public_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.

  1. Person A and Person B are friends on Facebook.
  2. 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.
  3. 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.
  4. 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 old locations 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 the user_checkins permission. Please use /me/tagged_places instead
  • /me/questions has been removed, along with the user_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 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.