Facebook Platform Upgrade Guide

Related Topics

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.4 to v2.5

Graph API

GET {user_id}/accounts

Now require either manage_pages or pages_show_list permission in v2.5.

Permissions for Call to Action

POST {page_id}/call_to_actions and POST/DELETE {call-to-action-id} require the new permission pages_manage_cta that we introduce in v2.5.

RTU Subscriptions Disabled

We now automatically disable RTU subscriptions if the callback URL fails for 7 days straight. You can reenable it with a POST request to /subscriptions. This change does not apply to payments subscriptions.

Marketing API Renaming

We now have consistent naming for three-level campaign structure between API and UI. This changes naming at endpoint, params, fields, and enum level. For the full list of changes, refer here.

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.

Questions?

If you have any questions, please check out the FAQs.