FBSession
This class is no longer available in the most recent version of the SDK.
A more recent version of this class is available. Check out the latest version.

The FBSession object is used to authenticate a user and manage the user's session. After initializing a FBSession object the Facebook App ID and desired permissions are stored. Opening the session will initiate the authentication flow after which a valid user session should be available and subsequently cached. Closing the session can optionally clear the cache.

If an FBRequest request requires user authorization then an FBSession object should be used.

Discussion:

Instances of the FBSession class provide notification of state changes in the following ways:

  1. Callers of certain `FBSession` methods may provide a block that will be called back in the course of state transitions for the session (e.g. login or session closed).
  2. The object supports Key-Value Observing (KVO) for property changes.
Inherits from:NSObject
Declared in:FBSession.h
Properties
accessToken

The access token for the session object.

@property (readonly, copy) NSString *accessToken __attribute__((deprecated
Discussion:

Deprecated. Use the accessTokenData property.

Declared In: FBSession.h
accessTokenData

Gets the FBAccessTokenData for the session

@property (readonly, copy) FBAccessTokenData *accessTokenData;
Declared In: FBSession.h
appID

Identifies the Facebook app which the session object represents.

@property (readonly, copy) NSString *appID;
Declared In: FBSession.h
expirationDate

The expiration date of the access token for the session object.

@property (readonly, copy) NSDate *expirationDate __attribute__((deprecated
Discussion:

Deprecated. Use the accessTokenData property.

Declared In: FBSession.h
isOpen

Indicates whether the session is open and ready for use.

@property (readonly) BOOL isOpen;
Declared In: FBSession.h
loginType

Specifies the login type used to authenticate the user.

@property (readonly) FBSessionLoginType loginType __attribute__((deprecated
Discussion:

Deprecated. Use the accessTokenData property.

Declared In: FBSession.h
permissions

The permissions granted to the access token during the authentication flow.

@property (readonly, copy) NSArray *permissions;
Declared In: FBSession.h
state

Detailed session state

@property (readonly) FBSessionState state;
Declared In: FBSession.h
urlSchemeSuffix

Identifies the URL Scheme Suffix used by the session. This is used when multiple iOS apps share a single Facebook app ID.

@property (readonly, copy) NSString *urlSchemeSuffix;
Declared In: FBSession.h
Class Methods
activeSession

An application may get or set the current active session. Certain high-level components in the SDK will use the activeSession to set default session (e.g. FBLoginView, FBFriendPickerViewController)

+ (FBSession*) activeSession;
Discussion:

If sessionOpen* is called, the resulting FBSession object also becomes the activeSession. If another session was active at the time, it is closed automatically. If activeSession is called when no session is active, a session object is instatiated and returned; in this case open must be called on the session in order for it to be useable for communication with Facebook.

Declared In: FBSession.h
defaultAppID

Get the default Facebook App ID to use for sessions. If not explicitly set, the default will be read from the application's plist. The app ID may be overridden on a per session basis.

+ (NSString*) defaultAppID;
Declared In: FBSession.h
defaultUrlSchemeSuffix

Get the default url scheme suffix used for sessions. If not explicitly set, the default will be read from the application's plist. The url scheme suffix may be overridden on a per session basis.

+ (NSString*) defaultUrlSchemeSuffix;
Declared In: FBSession.h
openActiveSessionWithAllowLoginUI:

This is the simplest method for opening a session with Facebook. Using sessionOpen logs on a user, and sets the static activeSession which becomes the default session object for any Facebook UI widgets used by the application. This session becomes the active session, whether open succeeds or fails.

Note, if there is not a cached token available, this method will present UI to the user in order to open the session via explicit login by the user.

ParameterDescription
allowLoginUI

Sometimes it is useful to attempt to open a session, but only if no login UI will be required to accomplish the operation. For example, at application startup it may not be disirable to transition to login UI for the user, and yet an open session is desired so long as a cached token can be used to open the session. Passing NO to this argument, assures the method will not present UI to the user in order to open the session.

+ (BOOL) openActiveSessionWithAllowLoginUI:(BOOL)allowLoginUI;
Discussion:

Returns YES if the session was opened synchronously without presenting UI to the user. This occurs when there is a cached token available from a previous run of the application. If NO is returned, this indicates that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is possible that the user will login, and the session will become open asynchronously. The primary use for this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session is opened via cache.

Declared In: FBSession.h
openActiveSessionWithPermissions:allowLoginUI:completionHandler:

This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user, and sets the static activeSession which becomes the default session object for any Facebook UI widgets used by the application. This session becomes the active session, whether open succeeds or fails.

ParameterDescription
permissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions. A nil value specifies default permissions.

allowLoginUI

Sometimes it is useful to attempt to open a session, but only if no login UI will be required to accomplish the operation. For example, at application startup it may not be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached token can be used to open the session. Passing NO to this argument, assures the method will not present UI to the user in order to open the session.

handler

Many applications will benefit from notification when a session becomes invalid or undergoes other state transitions. If a block is provided, the FBSession object will call the block each time the session changes state.

+ (BOOL)
openActiveSessionWithPermissions: (NSArray*)permissions
allowLoginUI: (BOOL)allowLoginUI
completionHandler: (FBSessionStateHandler)handler
__attribute__((deprecated));
Discussion:

Returns true if the session was opened synchronously without presenting UI to the user. This occurs when there is a cached token available from a previous run of the application. If NO is returned, this indicates that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is possible that the user will login, and the session will become open asynchronously. The primary use for this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session is opened via cache.

It is required that initial permissions requests represent read-only permissions only. If publish permissions are needed, you may use reauthorizeWithPermissions to specify additional permissions as well as an audience. Use of this method will result in a legacy fast-app-switch Facebook Login due to the requirement to seperate read and publish permissions for newer applications. Methods and properties that specify permissions without a read or publish qualification are deprecated; use of a read-qualified or publish-qualified alternative is preferred.

Declared In: FBSession.h
openActiveSessionWithPublishPermissions:defaultAudience:allowLoginUI:completionHandler:

This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user, and sets the static activeSession which becomes the default session object for any Facebook UI widgets used by the application. This session becomes the active session, whether open succeeds or fails.

ParameterDescription
publishPermissions

An array of strings representing the publish permissions to request during the authentication flow.

defaultAudience

Anytime an app publishes on behalf of a user, the post must have an audience (e.g. me, my friends, etc.) The default audience is used to notify the user of the cieling that the user agrees to grant to the app for the provided permissions.

allowLoginUI

Sometimes it is useful to attempt to open a session, but only if no login UI will be required to accomplish the operation. For example, at application startup it may not be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached token can be used to open the session. Passing NO to this argument, assures the method will not present UI to the user in order to open the session.

handler

Many applications will benefit from notification when a session becomes invalid or undergoes other state transitions. If a block is provided, the FBSession object will call the block each time the session changes state.

+ (BOOL)
openActiveSessionWithPublishPermissions: (NSArray*)publishPermissions
defaultAudience: (FBSessionDefaultAudience)defaultAudience
allowLoginUI: (BOOL)allowLoginUI
completionHandler: (FBSessionStateHandler)handler;
Discussion:

Returns true if the session was opened synchronously without presenting UI to the user. This occurs when there is a cached token available from a previous run of the application. If NO is returned, this indicates that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is possible that the user will login, and the session will become open asynchronously. The primary use for this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session is opened via cache.

Declared In: FBSession.h
openActiveSessionWithReadPermissions:allowLoginUI:completionHandler:

This is a simple method for opening a session with Facebook. Using sessionOpen logs on a user, and sets the static activeSession which becomes the default session object for any Facebook UI widgets used by the application. This session becomes the active session, whether open succeeds or fails.

ParameterDescription
readPermissions

An array of strings representing the read permissions to request during the authentication flow. A value of nil indicates basic permissions. It is not allowed to pass publish permissions to this method.

allowLoginUI

Sometimes it is useful to attempt to open a session, but only if no login UI will be required to accomplish the operation. For example, at application startup it may not be desirable to transition to login UI for the user, and yet an open session is desired so long as a cached token can be used to open the session. Passing NO to this argument, assures the method will not present UI to the user in order to open the session.

handler

Many applications will benefit from notification when a session becomes invalid or undergoes other state transitions. If a block is provided, the FBSession object will call the block each time the session changes state.

+ (BOOL)
openActiveSessionWithReadPermissions: (NSArray*)readPermissions
allowLoginUI: (BOOL)allowLoginUI
completionHandler: (FBSessionStateHandler)handler;
Discussion:

Returns true if the session was opened synchronously without presenting UI to the user. This occurs when there is a cached token available from a previous run of the application. If NO is returned, this indicates that the session was not immediately opened, via cache. However, if YES was passed as allowLoginUI, then it is possible that the user will login, and the session will become open asynchronously. The primary use for this return value is to switch-on facebook capabilities in your UX upon startup, in the case were the session is opened via cache.

Declared In: FBSession.h
renewSystemCredentials:

Issues an asychronous renewCredentialsForAccount call to the device Facebook account store.

ParameterDescription
handler

The completion handler to call when the renewal is completed. The handler will be invoked on the main thread.

+ (void) renewSystemCredentials:(FBSessionRenewSystemCredentialsHandler)handler;
Discussion:

This can be used to explicitly renew account credentials on iOS 6 devices and is provided as a convenience wrapper around [ACAccountStore renewCredentialsForAccount:completion]. Note the method will not issue the renewal call if the the Facebook account has not been set on the device, or if access had not been granted to the account (though the handler wil receive an error).

This is safe to call (and will surface an error to the handler) on versions of iOS before 6 or if the user logged in via Safari or Facebook SSO.

Declared In: FBSession.h
setActiveSession:

An application may get or set the current active session. Certain high-level components in the SDK will use the activeSession to set default session (e.g. FBLoginView, FBFriendPickerViewController)

ParameterDescription
session

The FBSession object to become the active session

+ (FBSession*) setActiveSession:(FBSession*)session;
Discussion:

If an application prefers the flexibilility of directly instantiating a session object, an active session can be set directly.

Declared In: FBSession.h
setDefaultAppID:

Set the default Facebook App ID to use for sessions. The app ID may be overridden on a per session basis.

ParameterDescription
appID

The default Facebook App ID to use for methods.

+ (void) setDefaultAppID:(NSString*)appID;
Declared In: FBSession.h
setDefaultUrlSchemeSuffix:

Set the default url scheme suffix to use for sessions. The url scheme suffix may be overridden on a per session basis.

ParameterDescription
urlSchemeSuffix

The default url scheme suffix to use for methods.

+ (void) setDefaultUrlSchemeSuffix:(NSString*)urlSchemeSuffix;
Declared In: FBSession.h
Instance Methods
close

Closes the local in-memory session object, but does not clear the persisted token cache.

- (void) close;
Declared In: FBSession.h
closeAndClearTokenInformation

Closes the in-memory session, and clears any persisted cache related to the session.

- (void) closeAndClearTokenInformation;
Declared In: FBSession.h
handleDidBecomeActive

A helper method that is used to provide an implementation for [UIApplicationDelegate applicationDidBecomeActive:] to properly resolve session state for the Facebook Login flow, specifically to support app-switch login.

- (void) handleDidBecomeActive;
Declared In: FBSession.h
handleOpenURL:

A helper method that is used to provide an implementation for [UIApplicationDelegate application:openURL:sourceApplication:annotation:]. It should be invoked during the Facebook Login flow and will update the session information based on the incoming URL.

ParameterDescription
url

The URL as passed to [UIApplicationDelegate application:openURL:sourceApplication:annotation:].

- (BOOL) handleOpenURL:(NSURL*)url;
Declared In: FBSession.h
init

Returns a newly initialized Facebook session with default values for the parameters to initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:.

- (id) init;
Declared In: FBSession.h
initWithAppID:permissions:defaultAudience:urlSchemeSuffix:tokenCacheStrategy:

Following are the descriptions of the arguments along with their defaults when ommitted.

ParameterDescription
permissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions. The default is nil.

defaultAudience

Most applications use FBSessionDefaultAudienceNone here, only specifying an audience when using reauthorize to request publish permissions.

appID

The Facebook App ID for the session. If nil is passed in the default App ID will be obtained from a call to <[FBSession defaultAppID]>. The default is nil.

urlSchemeSuffix

The URL Scheme Suffix to be used in scenarious where multiple iOS apps use one Facebook App ID. A value of nil indicates that this information should be pulled from the plist. The default is nil.

tokenCachingStrategy

Specifies a key name to use for cached token information in NSUserDefaults, nil indicates a default value of @"FBAccessTokenInformationKey".

- (id)
initWithAppID: (NSString*)appID
permissions: (NSArray*)permissions
defaultAudience: (FBSessionDefaultAudience)defaultAudience
urlSchemeSuffix: (NSString*)urlSchemeSuffix
tokenCacheStrategy: (FBSessionTokenCachingStrategy*)tokenCachingStrategy;
Discussion:

It is required that any single permission request request (including initial log in) represent read-only permissions or publish permissions only; not both. The permissions passed here should reflect this requirement. If publish permissions are used, then the audience must also be specified.

Declared In: FBSession.h
initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:

Following are the descriptions of the arguments along with their defaults when ommitted.

ParameterDescription
permissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions. The default is nil.

appID

The Facebook App ID for the session. If nil is passed in the default App ID will be obtained from a call to <[FBSession defaultAppID]>. The default is nil.

urlSchemeSuffix

The URL Scheme Suffix to be used in scenarious where multiple iOS apps use one Facebook App ID. A value of nil indicates that this information should be pulled from the plist. The default is nil.

tokenCachingStrategy

Specifies a key name to use for cached token information in NSUserDefaults, nil indicates a default value of @"FBAccessTokenInformationKey".

- (id)
initWithAppID: (NSString*)appID
permissions: (NSArray*)permissions
urlSchemeSuffix: (NSString*)urlSchemeSuffix
tokenCacheStrategy: (FBSessionTokenCachingStrategy*)tokenCachingStrategy;
Discussion:

It is required that any single permission request request (including initial log in) represent read-only permissions or publish permissions only; not both. The permissions passed here should reflect this requirement.

Declared In: FBSession.h
initWithPermissions:

Returns a newly initialized Facebook session with the specified permissions and other default values for parameters to initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:.

ParameterDescription
permissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions. The default is nil.

- (id) initWithPermissions:(NSArray*)permissions;
Discussion:

It is required that any single permission request request (including initial log in) represent read-only permissions or publish permissions only; not both. The permissions passed here should reflect this requirement.

Declared In: FBSession.h
openFromAccessTokenData:completionHandler:

Imports an existing access token and opens the session with it.

ParameterDescription
accessTokenData

The token data. See FBAccessTokenData for construction methods.

handler

A block to call with session state changes. The default is nil.

- (BOOL)
openFromAccessTokenData: (FBAccessTokenData *)accessTokenData
completionHandler: (FBSessionStateHandler)handler;
Discussion:

The method attempts to open the session using an existing access token. No UX will occur. If successful, the session with be in an Open state and the method will return YES; otherwise, NO.

The method may be called at most once and must be called after the FBSession is initialized (see below). It must be called before the session is closed. Calling the method at an invalid time will result in an exception. The open session methods may be passed a block that will be called back when the session state changes. The block will be released when the session is closed.

The initialized session must not have already been initialized from a cache (for example, you could use the [FBSessionTokenCachingStrategy nullCacheInstance] instance).

Declared In: FBSession.h
openWithBehavior:completionHandler:

Logs a user on to Facebook.

ParameterDescription
behavior

Controls whether to allow, force, or prohibit Facebook Login or Inline Facebook Login. The default is to allow Facebook Login, with fallback to Inline Facebook Login.

handler

A block to call with session state changes. The default is nil.

- (void)
openWithBehavior: (FBSessionLoginBehavior)behavior
completionHandler: (FBSessionStateHandler)handler;
Discussion:

A session may not be used with FBRequest and other classes in the SDK until it is open. If, prior to calling open, the session is in the FBSessionStateCreatedTokenLoaded state, then no UX occurs, and the session becomes available for use. If the session is in the FBSessionStateCreated state, prior to calling open, then a call to open causes login UX to occur, either via the Facebook application or via mobile Safari.

The method may be called at most once and must be called after the FBSession is initialized. It must be called before the session is closed. Calling the method at an invalid time will result in an exception. The open session methods may be passed a block that will be called back when the session state changes. The block will be released when the session is closed.

Declared In: FBSession.h
openWithCompletionHandler:

Opens a session for the Facebook.

ParameterDescription
handler

A block to call with the state changes. The default is nil.

- (void) openWithCompletionHandler:(FBSessionStateHandler)handler;
Discussion:

A session may not be used with FBRequest and other classes in the SDK until it is open. If, prior to calling open, the session is in the FBSessionStateCreatedTokenLoaded state, then no UX occurs, and the session becomes available for use. If the session is in the FBSessionStateCreated state, prior to calling open, then a call to open causes login UX to occur, either via the Facebook application or via mobile Safari.

Open may be called at most once and must be called after the FBSession is initialized. Open must be called before the session is closed. Calling an open method at an invalid time will result in an exception. The open session methods may be passed a block that will be called back when the session state changes. The block will be released when the session is closed.

Declared In: FBSession.h
reauthorizeWithPermissions:behavior:completionHandler:

Reauthorizes the session, with additional permissions.

ParameterDescription
permissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions. The default is nil.

behavior

Controls whether to allow, force, or prohibit Facebook Login. The default is to allow Facebook Login and fall back to Inline Facebook Login if needed.

handler

A block to call with session state changes. The default is nil.

- (void)
reauthorizeWithPermissions: (NSArray*)permissions
behavior: (FBSessionLoginBehavior)behavior
completionHandler: (FBSessionReauthorizeResultHandler)handler
__attribute__((deprecated));
Discussion:

Methods and properties that specify permissions without a read or publish qualification are deprecated; use of a read-qualified or publish-qualified alternative is preferred (e.g. reauthorizeWithReadPermissions or reauthorizeWithPublishPermissions)

Declared In: FBSession.h
reauthorizeWithPublishPermissions:defaultAudience:completionHandler:

Reauthorizes the session, with additional permissions.

ParameterDescription
writePermissions

An array of strings representing the permissions to request during the authentication flow.

defaultAudience

Specifies the audience for posts.

handler

A block to call with session state changes. The default is nil.

- (void)
reauthorizeWithPublishPermissions: (NSArray*)writePermissions
defaultAudience: (FBSessionDefaultAudience)defaultAudience
completionHandler: (FBSessionReauthorizeResultHandler)handler
__attribute__((deprecated));
Discussion:

This method is a deprecated alias of [FBSession requestNewPublishPermissions:defaultAudience:completionHandler:]. Consider using [FBSession requestNewPublishPermissions:defaultAudience:completionHandler:], which is preferred for readability.

Declared In: FBSession.h
reauthorizeWithReadPermissions:completionHandler:

Reauthorizes the session, with additional permissions.

ParameterDescription
readPermissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions.

handler

A block to call with session state changes. The default is nil.

- (void)
reauthorizeWithReadPermissions: (NSArray*)readPermissions
completionHandler: (FBSessionReauthorizeResultHandler)handler
__attribute__((deprecated));
Discussion:

This method is a deprecated alias of [FBSession requestNewReadPermissions:completionHandler:]. Consider using [FBSession requestNewReadPermissions:completionHandler:], which is preferred for readability.

Declared In: FBSession.h
requestNewPublishPermissions:defaultAudience:completionHandler:

Requests new or additional write permissions for the session.

ParameterDescription
writePermissions

An array of strings representing the permissions to request during the authentication flow.

defaultAudience

Specifies the audience for posts.

handler

A block to call with session state changes. The default is nil.

- (void)
requestNewPublishPermissions: (NSArray*)writePermissions
defaultAudience: (FBSessionDefaultAudience)defaultAudience
completionHandler: (FBSessionRequestPermissionResultHandler)handler;
Discussion:

The handler, if non-nil, is called once the operation has completed or failed. This is in contrast to the state completion handler used in [FBSession openWithCompletionHandler:] (and other open* methods) which is called for each state-change for the session.

Declared In: FBSession.h
requestNewReadPermissions:completionHandler:

Requests new or additional read permissions for the session.

ParameterDescription
readPermissions

An array of strings representing the permissions to request during the authentication flow. A value of nil indicates basic permissions.

handler

A block to call with session state changes. The default is nil.

- (void)
requestNewReadPermissions: (NSArray*)readPermissions
completionHandler: (FBSessionRequestPermissionResultHandler)handler;
Discussion:

The handler, if non-nil, is called once the operation has completed or failed. This is in contrast to the state completion handler used in [FBSession openWithCompletionHandler:] (and other open* methods) which is called for each state-change for the session.

Declared In: FBSession.h
Constants
FBSessionDidBecomeClosedActiveSessionNotification
extern NSString *const FBSessionDidBecomeClosedActiveSessionNotification;
Discussion:

NSNotificationCenter name indicating that there is no longer an open active session

Declared In: FBSession.h
FBSessionDidBecomeOpenActiveSessionNotification
extern NSString *const FBSessionDidBecomeOpenActiveSessionNotification;
Discussion:

NSNotificationCenter name indicating that the active session is open

Declared In: FBSession.h
FBSessionDidSetActiveSessionNotification
extern NSString *const FBSessionDidSetActiveSessionNotification;
Discussion:

NSNotificationCenter name indicating that a new active session was set

Declared In: FBSession.h
FBSessionDidUnsetActiveSessionNotification
extern NSString *const FBSessionDidUnsetActiveSessionNotification;
Discussion:

NSNotificationCenter name indicating that an active session was unset

Declared In: FBSession.h
Typedefs
FBSessionDefaultAudience enum

Passed to open to indicate which default audience to use for sessions that post data to Facebook.

typedef enum {
FBSessionDefaultAudienceNone = 0,
FBSessionDefaultAudienceOnlyMe = 10,
FBSessionDefaultAudienceFriends = 20,
FBSessionDefaultAudienceEveryone = 30,
} FBSessionDefaultAudience;
ConstantDescription
FBSessionDefaultAudienceNone

No audience needed; this value is useful for cases where data will only be read from Facebook

FBSessionDefaultAudienceOnlyMe

Indicates that only the user is able to see posts made by the application

FBSessionDefaultAudienceFriends

Indicates that the user's friends are able to see posts made by the application

FBSessionDefaultAudienceEveryone

Indicates that all Facebook users are able to see posts made by the application

Discussion:

Certain operations such as publishing a status or publishing a photo require an audience. When the user grants an application permission to perform a publish operation, a default audience is selected as the publication ceiling for the application. This enumerated value allows the application to select which audience to ask the user to grant publish permission for.

Declared In: FBSession.h
FBSessionLoginBehavior enum

Passed to open to indicate whether Facebook Login should allow for fallback to be attempted.

typedef enum {
FBSessionLoginBehaviorWithFallbackToWebView = 0,
FBSessionLoginBehaviorWithNoFallbackToWebView = 1,
FBSessionLoginBehaviorForcingWebView = 2,
FBSessionLoginBehaviorUseSystemAccountIfPresent = 3,
} FBSessionLoginBehavior;
ConstantDescription
FBSessionLoginBehaviorWithFallbackToWebView

Attempt Facebook Login, ask user for credentials if necessary

FBSessionLoginBehaviorWithNoFallbackToWebView

Attempt Facebook Login, no direct request for credentials will be made

FBSessionLoginBehaviorForcingWebView

Only attempt WebView Login; ask user for credentials

FBSessionLoginBehaviorUseSystemAccountIfPresent

Attempt Facebook Login, prefering system account and falling back to fast app switch if necessary

Discussion:

Facebook Login authorizes the application to act on behalf of the user, using the user's Facebook account. Usually a Facebook Login will rely on an account maintained outside of the application, by the native Facebook application, the browser, or perhaps the device itself. This avoids the need for a user to enter their username and password directly, and provides the most secure and lowest friction way for a user to authorize the application to interact with Facebook. If a Facebook Login is not possible, a fallback Facebook Login may be attempted, where the user is prompted to enter their credentials in a web-view hosted directly by the application.

The FBSessionLoginBehavior enum specifies whether to allow fallback, disallow fallback, or force fallback login behavior. Most applications will use the default, which attempts a normal Facebook Login, and only falls back if needed. In rare cases, it may be preferable to disallow fallback Facebook Login completely, or to force a fallback login.

Declared In: FBSession.h
FBSessionLoginType enum

Used as the type of the loginType property in order to specify what underlying technology was used to login the user.

typedef enum {
FBSessionLoginTypeNone = 0,
FBSessionLoginTypeSystemAccount = 1,
FBSessionLoginTypeFacebookApplication = 2,
FBSessionLoginTypeFacebookViaSafari = 3,
FBSessionLoginTypeWebView = 4,
FBSessionLoginTypeTestUser = 5,
} FBSessionLoginType;
ConstantDescription
FBSessionLoginTypeNone

A login type has not yet been established

FBSessionLoginTypeSystemAccount

A system integrated account was used to log the user into the application

FBSessionLoginTypeFacebookApplication

The Facebook native application was used to log the user into the application

FBSessionLoginTypeFacebookViaSafari

Safari was used to log the user into the application

FBSessionLoginTypeWebView

A web view was used to log the user into the application

FBSessionLoginTypeTestUser

A test user was used to create an open session

Discussion:

The FBSession object is an abstraction over five distinct mechanisms. This enum allows an application to test for the mechanism used by a particular instance of FBSession. Usually the mechanism used for a given login does not matter, however for certain capabilities, the type of login can impact the behavior of other Facebook functionality.

Declared In: FBSession.h
FBSessionReauthorizeResultHandler

Block type used to define blocks called by [FBSession reauthorizeWithPermissions].

typedef FBSessionRequestPermissionResultHandler FBSessionReauthorizeResultHandler __attribute__((deprecated));
Discussion:

You should use the preferred FBSessionRequestPermissionHandler typedef rather than this synonym, which has been deprecated.

Declared In: FBSession.h
FBSessionRenewSystemCredentialsHandler

Block type used to define blocks called for system credential renewals.

typedef void (^FBSessionRenewSystemCredentialsHandler)(
ACAccountCredentialRenewResult result,
NSError *error);
Declared In: FBSession.h
FBSessionRequestPermissionResultHandler

Block type used to define blocks called by [FBSession requestNewReadPermissions:completionHandler:] and [FBSession requestNewPublishPermissions:defaultAudience:completionHandler:].

typedef void (^FBSessionRequestPermissionResultHandler)(
FBSession *session,
NSError *error);
Discussion:

See https://developers.facebook.com/docs/technical-guides/iossdk/errors/ for error handling best practices.

Declared In: FBSession.h
FBSessionState enum

Passed to handler block each time a session state changes

typedef enum {
FBSessionStateCreated = 0,
FBSessionStateCreatedTokenLoaded = 1,
FBSessionStateCreatedOpening = 2,
FBSessionStateOpen = 1 | FB_SESSIONSTATEOPENBIT,
FBSessionStateOpenTokenExtended = 2 | FB_SESSIONSTATEOPENBIT,
FBSessionStateClosedLoginFailed = 1 | FB_SESSIONSTATETERMINALBIT,
FBSessionStateClosed = 2 | FB_SESSIONSTATETERMINALBIT,
} FBSessionState;
ConstantDescription
FBSessionStateCreated

One of two initial states indicating that no valid cached token was found

FBSessionStateCreatedTokenLoaded

One of two initial session states indicating that a cached token was loaded; when a session is in this state, a call to open* will result in an open session, without UX or app-switching

FBSessionStateCreatedOpening

One of three pre-open session states indicating that an attempt to open the session is underway

FBSessionStateOpen

Open session state indicating user has logged in or a cached token is available

FBSessionStateOpenTokenExtended

Open session state indicating token has been extended

FBSessionStateClosedLoginFailed

Closed session state indicating that a login attempt failed

FBSessionStateClosed

Closed session state indicating that the session was closed, but the users token remains cached on the device for later use

Declared In: FBSession.h
FBSessionStateHandler

Block type used to define blocks called by FBSession for state updates

typedef void (^FBSessionStateHandler)(
FBSession *session,
FBSessionState status,
NSError *error);
Discussion:

See https://developers.facebook.com/docs/technical-guides/iossdk/errors/ for error handling best practices.

Declared In: FBSession.h