Facebook Application Development FAQ

This document covers many of the more common questions developers ask when building apps with Facebook.

Migration to v2.0

At F8 2014, we introduced Graph API v2.0, updates to Facebook Login, and a lightweight Login Review process in order to give people more control over the information they share with apps.

We gave developers a year to upgrade their apps, so on April 30, 2015, we will start automatically upgrading apps to Graph API v2.0, and removing access to any permissions which have not been approved for use via Login Review.

As soon as possible. You can opt-in to the changes at any time by updating your app to call API v2.0, or by enabling the Use Graph API v2.0 by default switch in your app's migration settings to upgrade your app without making any code changes. If you do not upgrade your app, it will be automatically upgraded on or after April 30, 2015.

On April 30, 2015 the following changes will come into effect:

  • For apps created before April 30, 2014, all unversioned API requests will behave as v2.0 requests - this includes response formats, response contents and permission availability.
  • If your app uses Facebook Login, everyone that logs in will see the new Login Dialog and can uncheck any permission except public_profile.
  • /me/friends will only return a person's friends who also use the app.
  • Anyone logging into your app for the first time will be known by an app-scoped user ID.
  • Any deprecated permissions will be removed from existing users, and won't be grantable by new users. This includes the friends_* permissions, xmpp_login or user_checkins.
  • Apps will need to request the user_friends permission in order to access a person's friend list or use the Taggable Friends and Invitable Friends APIs.
  • Please see our Changelog and Upgrade Guide for more details.

Starting on April 30th, we'll gradually migrate all apps still using API v1.0 to API v2.0. We will also remove access to any permissions that have not been approved for use via Login Review. If developers have already upgraded their app to call Graph API v2.0, they won't see any changes. If an app is still using Graph API v1.0, we recommend developers upgrade as soon as possible.

People using apps that have not been upgraded may see errors or functionality not working as expected starting on April 30th. Developers can opt-in to the changes at any time by updating their apps to call API v2.0, or by enabling the Use Graph API v2.0 by default switch in their app's migration settings to upgrade an app without making any code changes. Starting April 30, developers will be able to see if their app has been automatically upgraded by going to their app's dashboard.

  • /me/friends now returns only the friends who also use your app, see /me/friends changes.
  • Permissions other than public_profile, user_friends and email can only be accessed if they've been approved through Login Review
  • Some API endpoints are deprecated, see Platform Changelog.
  • Some permissions are deprecated Platform Changelog.
  • Some fields, such as username are no longer in API responses

If you're still not sure what's going on with your app, post a question in the Facebook Developer Community Group. If you're certain you've found a bug and can consistently reproduce it across multiple App IDs, file a bug at Facebook Developer Support, Bugs.

Check the API Version field in your App Dashboard. If this shows v2.0 or later, your app has been migrated.

When apps make unversioned calls to the Graph API, our servers convert these requests to the oldest available version an app can access. The minimum version your app can access depends on when your app was created, see Calling Older Versions.

For apps created before April 30, 2014, the oldest available version is changing from v1.0 to v2.0. All calls made without specifying a version will behave as v2.0 calls. In addition, any calls that specify v1.0 will be converted to v2.0 beha

Apps created after April 30, 2014 can only request v2.0 or higher.

Apps created before April 30, 2014 will be migrated to v2.0 beginning April 30, 2015. We expect this process to take a few weeks, so if you have multiple apps they may not be migrated at the same time. You can check the minimum API version your app can call in the App Dashboard.

Rather than waiting for Facebook to migrate your app, you can opt in to v2.0 and enforce Login Review by selecting Use Graph API v2.0 by default and Enforce Login Review in the Migrations section of your App Dashboard. These toggles disappear after your app is migrated.

  • Apps using mobile SDKs earlier than v3.14 make unversioned API calls and may be affected by this change. How your app is affected depends on the features you're using and how you coded you app. To resolve these issues, upgrade your iOS or Android app to at least v3.14 of the SDK or higher. We recommend upgrading to v4.0 for easier development in the future and the best user experience. Get the lastest SDK for iOS or Android.
  • You can update your iOS, Android and Web versions of your app in any order and on different timelines. But, given that our data shows it may take up to 140 days for 90% of an app's active mobile users to upgrade to the most recent binary, we suggest you upgrade your Android and iOS apps to the latest SDK v4.0 as soon as possible.
  • It's possible people may use your app on multiple platforms such as iOS, Android and Web - some of which you may have not yet upgraded to v2.0. In these cases, a logged in user will be known by the same ID across both v1.0 and v2.0+ versions. For detailed instructions for how to handle people using different versions of the API at the same time, see the Upgrade Guide.
  • No. After April 30, 2015, all apps will automatically be upgraded to v2.0. To be clear:
  • Apps already calling v2.0 or later will continue to get the same behavior.
  • Calling the API without a version number will automatically result in v2.0 behavior.
  • Calls that declare v1.0 will also automatically experience v2.0 behavior.

The New Login and Login Review

No. In general, we are not granting exceptions or extensions.

The new version of Facebook Login lets people edit the information they provide to your app when they log in. We made this change because we heard from people that they want more control over the information they share with apps.

It's important for your app to have a Login experience that works well for people no matter what permissions they grant or decline. Developers should update their apps to gracefully handle the cases where people choose to decline one or more permissions.

We introduced the review process as a way to ensure the best possible Facebook experience for your app's audience. The app review process aims to help people feel in control of how your app is using their data by requesting only the permissions your app needs to provide a great user experience.

After your app has been upgraded to API v2.0 and Login Review is enforced:

  • Only permissions that have been approved through Login Review will appear in the Login dialog
  • People logging into your app won't be able to grant unapproved permissions
  • Only approved permissions can be used in API calls
  • Calls to the Graph API will behave as if existing users haven't granted unapproved permissions

Only the basic permissions do not require Login Review. This includes email, user_friends, and public_profile.

To help resolve any issues your app may have after migration, you should either submit it for Login Review or update your app so it no longer relies on unapproved permissions.

People listed in the Roles section of your App Dashboard - including Admins, Developers and Testers - can grant any permission without review. If only people in these Roles will use your app, you don't need to submit it for Login Review.

Login Review is mandatory if your app asks for more than public_profile, email and user_friends permissions. Apps that do not request permissions beyond these three permissions do not need to undergo Login Review. After April 30th, we will start removing access to any permissions which have not been approved for use via Login Review.

  • No, it does not have to be reviewed. If your app is only used by a very limited number of people - for example, to use the Facebook for Wordpress plugin to publish to your profile - it's completely normal to list them all as having different roles in your app's dashboard. They can be listed as Admins, Developers or Testers
  • Some background on this: To enable you to develop and fully test your app, anyone listed in the Role section of your app's dashboard can be granted any permission necessary to test without review by Facebook. The purpose of Login Review is to protect the experiences of regular people who may interact with your app. Directly adding a small set of well-known people directly to your app is used for software development, testing and small application deployments.

Friend Permissions

To put people first. This update was in response to feedback from people who were uncomfortable knowing that a friend could share their information with an app. With Graph API v2.0, we wanted to make sure that people had more control over their information.

  • With Graph API v2.0 and above, calls to /me/friends return only the friends who also use your app. These friends must have also granted the user_friends permission. In the cases where you want to let people tag their friends in stories published by your app, you can use the Taggable Friends API.
  • If you want to invite people to your app, we have a number of solutions that depend on the type of app you've built and the platforms you've built for. Please see our question about Inviting Friends for more information.

The read_friendlists permission lets apps access the names of custom friend lists that someone created to manage their friends. It does not give you access to the people within each friendlist, nor all of a person's friends. This permission is only useful if you want to render a custom audience selector to let people choose the audience who see the content they publish from your app.

  • The ability to post on another person's wall via the Graph API was deprecated in October 2012 because those posts typically generated negative feedback from people receiving the post. This feature remained on the Feed Dialog but was removed in v2.0.
  • Apps can let people share content directly with their friends via a message using the Message Dialog on iOS or Android and the Send Dialog on Web.

As of Tuesday 22nd July 2014, we now return a total_count field within a summary property in the response to /v2.0/me/friends. This means all upgraded apps now have access to a person's total friend count in all calls to the friends edge.

This is a new feature that allows apps to offer services that are tailored based on a person's group of friends. For example, a dating app can use all_mutual_friends to display the people you and a potential match have in common. Note: Facebook must approve the use of this feature before apps can use it.

This feature lets an app display the list of mutual friends between two people who both use the app. Both people must have granted the user_friends permission. For friends who have not granted the permission, the app receives limited information (their name, profile picture and a token which the app can use to link to that person's Facebook profile). In addition, Facebook must approve the use of this feature before apps can use it.

Your app should use the filters= parameter on the Request Dialog. Set filters=app_users to filter the Request Dialog to people that use the app. Set filters=app_non_users to filter the Request Dialog to people that do not use the app. See the Game Requests documentation for more information.

If your app is a game and has a presence on Facebook Canvas:

  • You can use the Game Requests Dialog with the filter parameter to only show people who don't use the app.

  • If your app category is set to Game and you want to build your own multi-friend selector, you may use the Invitable Friends API, which returns a ranked list of the person's friends who do not use the app. Once a person has selected a number of friends to invite, you may pass the tokens returned by the Invitable Friends API to the to field of the Requests Dialog, which will then let the person send an invite to those friends.

  • Only apps with a category set to Game can use Game Requests. Non-game Canvas apps are unable to use this feature.

If your app is a game but does not have a presence on Canvas, you can still render the Requests Dialog with no friends pre-selected. Access to the Invitable Friends API is not required in order to let people invite their friends to use your game.

If your app is not a game and has a mobile presence:

  • You can use App Invites on iOS and Android to allow people to invite their Facebook friends to use your app, in a rich and personalized way.

If your app is not a game and has a mobile or web presence:

  • You can also use the Message Dialog on iOS and Android, or the Send Dialog on Web. These products let a person send a message directly to their friends containing a link to your app. This type of message is a great channel for communicating with a smaller number of people in a direct way. The Message Dialog and the Send Dialog both include a typeahead which lets the person easily select a number of friends to receive the invite.
  • The list of someone's friends who don't use your app is no longer available in v2.0. However, you can still enable people to tag friends using the Taggable Friends API.
  • Also, If your app is categorized as a game and you have a presence on Facebook Canvas, you can use the Invitable Friends API to render a custom invites dialog within your game. However, you'll still need to pass the tokens returned by the Invitable Friends API to the Requests Dialog to actually send the invites.

We've removed access to friends' data in v2.0. However, we still support tagging friends through a new Taggable Friends API that you can use in your app.

  • The Invitable Friends API is available to games with a Canvas presence as it's a very common design pattern for games to render custom multi-friend selectors within the style of the game, often within the Flash object itself.
  • For apps which are not games, or for apps without a Canvas presence, use our other products such as the Message Dialog on iOS and Android, Send Dialog for the Web or the Share Dialog on iOS, Android, Web. These products let a person easily select the friends they want to message or share with.

App-Scoped IDs

Facebook will begin to issue app-scoped user IDs when people first log into an instance of an app that has been upgraded to API v2.0 or above. Previously, a user was known by the same ID across every app. With app-scoped IDs, the ID for the same user will be different between apps. This makes it harder for a user's data to be passed between apps, which helps protect people's information. For people who have already logged into an app, their ID will not change.

You can use the Business Mapping API to determine the ID for a given person across the multiple apps your business operates. To help during the development, testing, QA and staging phases of your app development lifecycle, you can use Test Apps which emit the same app-scoped user IDs as their parent App ID uses in production.

The ID will not change for people who already logged into your app. It will remain locked as the user's original Facebook ID.

New users will be assigned an app-scoped ID when they log into your app for the first time.

If your app stores the IDs of people who do not use your app, such as the IDs of people who comment on your Page's posts, these IDs will change from their original ID to an app-scoped ID. There is no way to convert an original ID to an app-scoped ID.

In the majority of cases, the ID remains the same; your app gets the original Facebook user ID , since the user logged into your app in the past. There are a very small number of cases where their ID may change to an app-scoped ID. These cases may occur if the user originally logged into your app several years ago.

API v2.0 introduced app-scoped IDs to help protect people's information. The username field for a user was the same across apps, so we removed it for the same reasons we introduced app-scoped IDs.

Instead of using Facebook username, we recommend you build your own username generator. For example you could take the user's name such as “John Doe” and create a username of your own such as johndoe.

Users can use the App Settings dialog to find their app-scoped ID for your app. We have provided a help topic for users here: How do I find my user ID for my apps and games?

We understand that for apps which operate a Page as well as the app, it's often valuable (for example, for customer support questions) to be able to understand which of your app's users are posting, liking and commenting on your Page. When you call the Page Feed API /VERSION/{page-id}/feed) with your app's access token, people who have logged into your app will be known by the same IDs in the Page's feed as they are known to your app.

Miscellaneous

Hashtag and Keyword Search

With the Topic Feed API you can get a feed of public posts containing a keyword or hashtag. This API is available to companies that are part of our Media Solutions Program. We recommend you work with these companies to access data about posts mentioning keywords or hashtags.

Also we recently announced Topic Data, a partnership with DataSift. Topic data shows marketers what audiences say on Facebook about events, brands, subjects and activities, in a way that keeps personal information private. Marketers can use this information to make better decisions about their Facebook activity. Please contact DataSift directly for more information.

You can still continue searching for posts using the native search functionality within Facebook's iOS and Android apps or on facebook.com.

XMPP Chat API

Handling Declined Permissions

  • People who use your app may decline to share some data with it. Your app must be able to gracefully handle missing permissions.
  • Your app may re-ask for a missing permission in order to educate someone about why that permission might be important, but it's only allowed to ask once.
  • For information on how to check for missing permissions, please see our documentation on Missing Permissions.

For more information, also see this blog post Tips for Building Better Experiences with the New Facebook Login.

Other

Using the user_likes permission for the sole purpose of determining if a user has liked your page is not an appropriate use of this permission and will be rejected as part of our review process. The user_likes permission should be used to help you personalize a person's experience within your app based on the things they have liked.

Errors

On October 14, 2014, we dropped support for SSL 3.0 across Facebook properties, including the Facebook Platform API and the Real-Time Updates API, after a vulnerability in the protocol was revealed that day. This change helps protect people’s information.

This means that clients currently using SSL 3.0 to connect to Facebook's servers must upgrade to use TLS. Facebook PHP SDK 3.1.1 and older - that used SSL 3.0 - will no longer work. Please upgrade to a version of our SDK that supports TLS: Facebook SDK 3.2.3 or greater.

Many problems can cause this symptom but if calls made before October 14th, 2014 worked and newer ones don't, it's possible that your client is using SSL version 3.0. Please see our FAQ entry about the SSL 3.0 change made that day.