Facebook SDK for iOS Upgrade Guide

Upgrading to 4.23.0

No special steps are required to upgrade to 4.23.0.

Upgrading to 4.22.1

No special steps are required to upgrade to 4.22.1.

Upgrading to 4.22.0

The title, description, caption and image field of FBSDKShareLinkContent have been deprecated. Please take appropriate action to remove usage of them.

Upgrading to 4.21.0

No special steps are required to upgrade to 4.21.0.

Upgrading to 4.20.2

No special steps are required to upgrade to 4.20.2.

Upgrading to 4.20.1

No special steps are required to upgrade to 4.20.1.

Upgrading to 4.20.0

No special steps are required to upgrade to 4.20.0.

Upgrading to 4.19.0

Basic App Events are now auto logged after initializing the Facebook SDK. Calls to activateApp can now be removed from your application. This feature can be disabled by following the instructions in App Events for iOS online documentation.

The FBSDKLoginButton UI has changed in 4.19.0. Instead of "Log in with Facebook", the button now displays "Continue with Facebook". The button color is changed to #4267B2 from #3B5998. The button height is now fixed at 28 due to use of smaller font size and paddings around a larger Facebook logo.

The interface for using FBSDKLoginButton remains the same. Please take time to ensure the updated FBSDKLoginButton does not break your app's UX

Upgrading to 4.18.0

No special steps are required to upgrade to 4.18.0.

Upgrading to 4.17.0

No special steps are required to upgrade to 4.17.0.

Upgrading to 4.16.1

No special steps are required to upgrade to 4.16.1.

Upgrading to 4.16.0

No special steps are required to upgrade to 4.16.0.

Upgrading to 4.15.0

The FBSDKAppGroupAddDialog and FBSDKAddGroupJoinDialog interfaces have been deprecated. Please take appropriate action to remove usage of them.

Upgrading to 4.14.0

No special steps are required to upgrade to 4.14.0.

Upgrading to 4.13.1

No special steps are required to upgrade to 4.13.1.

Upgrading to 4.13.0

No special steps are required to upgrade to 4.13.0.

Upgrading to 4.12.0

No special steps are required to upgrade to 4.12.0.

Upgrading to 4.11.0

No special steps are required to upgrade to 4.11.0. Note the SDK targets v2.6 of the Graph API.

Upgrading to 4.10.0

No special steps are required to upgrade to 4.10.0.

Upgrading to 4.9.0

No special steps are required to upgrade to 4.9.0.

Upgrading to 4.8.0

No special steps are required to upgrade to 4.8.0.

Upgrading to 4.7.1

No special steps are required to upgrade to 4.7.1.

Upgrading to 4.7.0

No special steps are required to upgrade to 4.7.0. Note the SDK targets v2.5 of the Graph API.

Upgrading to 4.6.0 (or 3.24)

In order to support iOS 9, you should upgrade your Facebook iOS SDK 4.x to 4.6.0. If you are on 3.x of the SDK, you should move to v3.24. There are two key steps you follow after you upgrade to the SDK:

  1. Update your application plist as described in our Follow the our Preparing for iOS 9 guide.
  2. Several methods on FBSDKLoginManager and FBSDKAppInviteDialog have been deprecated in favor of new overloads that take a fromViewController parameter. This resolves various presentation issues that can occur on iOS 9. You should update any calls to deprecated methods to the new overloads.

Upgrading to 3.24 (only if you have not migrated to 4.x yet)

  1. Update your application plist as described in our Follow the our Preparing for iOS 9 guide.
  2. Several methods on FBSession have been deprecated in favor of new overloads that take a fromViewController parameter. This resolves various presentation issues that can occur on iOS 9. You should update any calls to deprecated methods to the new overloads.
  3. Make sure you are connecting your application delegate's application:openURL:sourceApplication:annotation: to [FBAppCall handleOpenURL:sourceApplication: (and not -[FBSession handleOpenURL:]). This is necessary to complete any SafariViewController flows.

Upgrading from 4.5.0 to 4.5.1

No special steps are required to upgrade to 4.5.1.

Upgrading from 4.4.0 to 4.5.0

No special steps are required to upgrade to 4.5.0, but you should review preparing your app for iOS9.

Upgrading from 4.3.0 to 4.4.0

No special steps are required to upgrade to 4.4.0. Note the SDK targets v2.4 of the Graph API.

Upgrading from 4.2.0 to 4.3.0

No special steps are required to upgrade to 4.3.0.

Upgrading from 4.1.0 to 4.2.0

The property FBSDKShareAPI.createObjectsWithClientToken was removed. Open Graph Object shares will use the current user access token.

The property FBSDKAppInviteContent.previewImageURL is deprecated. Use FBSDKAppInviteContent.appInvitePreviewImageURL instead.

The property FBSDKGameRequestContent.to is deprecated. Use FBSDKGameRequestContent.recipients instead.

The property FBSDKGameRequestContent.suggestions is deprecated. Use FBSDKGameRequestContent.recipientSuggestions instead.

Otherwise, there are no special steps are required to upgrade to 4.2.0.

Upgrading from 4.0 to 4.0.1

No special steps are required to upgrade to 4.0.1.

Upgrading from 4.0.1 to 4.1.0

The method FBSDKAppInviteContent initWithAppLinkURL: was removed. Use the standard init method and set the appLinkURL property instead.

Upgrading from 4.0 to 4.0.1

No special steps are required to upgrade to 4.0.1.

iOS SDK, Upgrading from 3.x to 4.x

The Facebook SDK for iOS v4.0 is a major version upgrade which features:

  • Improved login programming model.
  • Improved sharing programming model, and more ways to share without having to log in.
  • Improved error programming model and new error recovery mechanism.
  • The SDK is now composed of three frameworks, FBSDKCoreKit, FBSDKLoginKit, and FBSDKShareKit.
  • FBSDKCoreKit provides core SDK functionality such as Graph API Requests, access tokens, and App Insights.
  • FBSDKLoginKit provides functionality to log people in, and only requires FBSDKCoreKit.
  • FBSDKShareKit provides functionality to share, and only requires FBSDKCoreKit.
  • You can also specify kit subspecs in Cocoapods.

Install and Setup Updates

For full instructions on install and setup for 4.x, see Getting Started for iOS.

  • Set up .plist entries for FacebookAppID and URL types as in v3.x.
  • Link FBSDKCoreKit.framework to your project.
  • Connect your UIApplicationDelegate to the FBSDKCoreKit. See iOS Getting Started, Start Coding

Login Updates

For more information on Login in 4.x, also see Facebook Login for iOS.

Performing login, getting permissions:

  • FBSDKLoginManager performs the login flow and works with the [FBSDKAccessToken currentAccessToken]. After a successfully login, the currentAccessToken will be set.
  • To request additional permissions, simply call the logInWith...: method again with a set currentAccessToken.
  • LoginManager logIn: methods always open a UI. There is no direct equivalent to v3.x's FBSession's allowLoginUI: flag. Instead, you should check [FBSDKAccessToken currentAccessToken] at viewDidLoad or similar. If a current token is available, do the post-login work. You can also use currentAccessToken to retrieve cached tokens.

Access tokens:

  • FBAccessTokenData is replaced by FBSDKAccessToken.
  • FBSession.activeSession has been replaced with [FBSDKAccessToken currentAccessToken] and FBSDKLoginManager. There is no concept of session state. Instead, use the manager to login and this sets the currentAccessToken reference.
  • FBSDKTokenCachingStrategy is removed. Setting currentAccessToken automatically caches it in the keychain. You can observe the token change notification in order to do additional post processing of tokens.
  • [FBSDKAccessToken currentAccessToken] - You can load this with the SDK from a keychain cache or from an app bookmark when your app cold launches. You should check its availability in your view controller's viewDidLoad.
  • FBSDKAccessToken currentAccessToken broadcasts notifications when it is set or unset.
  • If you want to switch accounts, save the currentAccessToken which implements NSSecureCoding. Then set the currentAccessToken to nil, and then invoke the FBSDKLoginManager.

Logged-in user

  • Use FBSDKProfilePictureView to easily display the profile image of someone.
  • Use FBSDKProfile currentProfile to easily fetch current profile information. You can use this type instead of manually fetching /me.
  • By default the FBSDKLoginButton displays a tooltip NUX to increase engagement with Graph API 2.0 Login. You can replicate the tooltip on your own login buttons with FBSDKLoginTooltipView.
  • FBLoginViewDelegate is replaced by FBSDKLoginButtonDelegate which no longer fetches profile data like name. Use FBSDKProfile instead for profile information.

Graph API Update

  • Requests - FBSDKGraphRequest and FBSDKGraphRequestConnection are in FBSDKCoreKit and provide helpers to access the Graph API. They are very similar to FBRequest and FBRequestConnection in v3.x. By default they use [FBSDKAccessToken currentAccessToken] for issuing requests so you typically issue requests after login. For example:
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc] initWithGraphPath:@"me"
                                                                 parameters:nil];
  [request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection, id result, NSError *error) {
    // TODO: handle results or error of request.
  }];

  • Batch Requests - As in v3.x, you construct a FBSDKGraphRequestConnection to add multiple requests to send in a batch.

  • FBViewController and related picker classes such as FBCacheDescriptor have been removed. If you want to display Graph API results in a table view, you can do it manually. Take a look at the Scrumptious or RPSSample for ideas to get started.

Error Handling and Recovery

For details about error messages, error handling and recovery in 4.x+, see Error-Handling, iOS SDK.

  • FBErrorUtility has been removed. Instead use NSError objects returned in request callbacks and are simpler to interpret. See Error Handling, iOS SDK
  • NSError instances also contain data conforming to the informa protocol NSErrorRecoveryAttempting. This makes it easier for you to extract information about any recovery attempts and re-attempt recovery. See Error Handling, iOS SDK.
  • To make it simpler to subscribe to best practices, the SDK provides FBSDKGraphErrorRecoveryProcessor which can process errors for you, such as presenting alerts or dialogs automatically. See its reference docs for details.
  • Non-batched FBSDKGraphRequests will automatically use FBSDKGraphErrorRecoveryProcessor so that transient errors and recoverable errors that succeed are automatically retried once. You can disable this by setting -[FBSDKGraphRequest setGraphErrorRecoveryDisabled:YES] (There is also a global toggle in FBSDKSettings).

Sharing Updates

Sharing is simplified into two concepts: a sharing implementation that conforms to FBSDKSharing such as FBSDKShareDialog, and a content model that conforms to FBSDKSharingContent. For more information, see Sharing on iOS.

  • First, link the FBSDKShareKit.framework

Dialogs and buttons:

  • FB*Dialogs, FB*Params and related classes have been removed.

  • Share dialogs also provide methods for validation and customization. See their reference docs.

  • Drop-in replacement buttons are available for sharing. This includes FBSDKShareButton and FBSDKSendButton.

  • FBWebDialogs is replaced by strongly typed dialogs. See FBSDKGameRequestDialog, FBSDKAppGroupAddDialog, FBSDKAppGroupJoinDialog.

  • FBSDKAppInviteDialog is now available to provide a way to invite friends to use your app.

Open Graph, sharing:

  • FBGraphObject and related protocols are removed such as FBGraphUser. Open Graph types are defined more completely in FBSDKShareKit.framework and used there for sharing. Otherwise you can simply work with NSDictionary instances to represent Facebook Graph entities.

  • FBRequest request* helpers have been removed with one exception. requestForCustomAudienceThirdPartyIDWithAccessToken has been moved to FBSDKAppEvents. You can construct the appropriate graph path manually.

App Events

  • No programming model changes. Use FBSDKAppEvents in FBSDKCoreKit.framework to log events taken in your app to get useful analytics. This includes app installs, time spent in your app and ad targeting.
  • FBAppLinkData is removed. You should link the Bolts.framework included in the pkg and use BFURL. Bolts is no longer statically linked to the FBSDK frameworks so there are no more duplicate symbol linking errors.
  • Use FBSDKAppLinkResolver to resolve App Links efficiently with Facebook servers.
  • Use FBSDKUtility to help parse URLs.

Localization