FBSession - Documentación - Meta for Developers

FBSession

Esta clase no está disponible en la última versión del SDK.
Existe una versión más reciente de esta clase. Consulta la última versión.

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:

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).
The object supports Key-Value Observing (KVO) for property changes.

Inherits from:	`NSObject`
Declared in:	`FBSession.h`

Propiedades

accessToken

The access token for the session object.

@property (readonly,
    copy) NSString *accessToken;

Declarado en: FBSession.h

appID

Identifies the Facebook app which the session object represents.

@property (readonly,
    copy) NSString *appID;

Declarado en: FBSession.h

expirationDate

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

@property (readonly,
    copy) NSDate *expirationDate;

Declarado en: FBSession.h

isOpen

Indicates whether the session is open and ready for use.

@property (readonly) BOOL isOpen;

Declarado en: FBSession.h

permissions

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

@property (readonly,
    copy) NSArray *permissions;

Declarado en: FBSession.h

state

Detailed session state

@property (readonly) FBSessionState state;

Declarado en: 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;

Declarado en: FBSession.h

Métodos de clase

activeSession

An appication 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.

Declarado en: 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;

Declarado en: 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.

Parámetro Descripción

Parámetro	Descripción
`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.

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.

Declarado en: 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.

Parámetro	Descripción
`permissions`	An array of strings representing the permissions to request during the authentication flow. A value of nil will 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;`

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.

Declarado en: FBSession.h

setActiveSession:

Parámetro	Descripción
`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.

Declarado en: FBSession.h

setDefaultAppID:

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

Parámetro	Descripción
`appID`	The default Facebook App ID to use for methods.

+ (void) setDefaultAppID:(NSString*)appID;

Declarado en: FBSession.h

Métodos de instancia

close

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

- (void) close;

Declarado en: FBSession.h

closeAndClearTokenInformation

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

- (void) closeAndClearTokenInformation;

Declarado en: 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.

Parámetro	Descripción
`url`	The URL as passed to [UIApplicationDelegate application:openURL:sourceApplication:annotation:].

- (BOOL) handleOpenURL:(NSURL*)url;

Declarado en: FBSession.h

init

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

- (id) init;

Declarado en: FBSession.h

initWithAppID:permissions:urlSchemeSuffix:tokenCacheStrategy:

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

Parámetro	Descripción
`permissions`	An array of strings representing the permissions to request during the authentication flow. A value of nil will 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;`

Declarado en: FBSession.h

initWithPermissions:

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

Parámetro	Descripción
`permissions`	An array of strings representing the permissions to request during the authentication flow. A value of nil will indicates basic permissions. The default is nil.

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

Declarado en: FBSession.h

openWithBehavior:completionHandler:

Logs a user on to Facebook.

Parámetro	Descripción
`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.

Declarado en: FBSession.h

openWithCompletionHandler:

Opens a session for the Facebook.

Parámetro	Descripción
`handler`	A block to call with the state changes. The default is nil.

- (void) openWithCompletionHandler:(FBSessionStateHandler)handler;

Discussion:

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.

Declarado en: FBSession.h

reauthorizeWithPermissions:behavior:completionHandler:

Reauthorizes the session, with additional permissions.

Parámetro	Descripción
`permissions`	An array of strings representing the permissions to request during the authentication flow. A value of nil will 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;`

Declarado en: FBSession.h

Constantes

FBSessionDidBecomeClosedActiveSessionNotification

extern NSString *const FBSessionDidBecomeClosedActiveSessionNotification;

Discussion:

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

Declarado en: FBSession.h

FBSessionDidBecomeOpenActiveSessionNotification

extern NSString *const FBSessionDidBecomeOpenActiveSessionNotification;

Discussion:

NSNotificationCenter name indicating that the active session is open

Declarado en: FBSession.h

FBSessionDidSetActiveSessionNotification

extern NSString *const FBSessionDidSetActiveSessionNotification;

Discussion:

NSNotificationCenter name indicating that a new active session was set

Declarado en: FBSession.h

FBSessionDidUnsetActiveSessionNotification

extern NSString *const FBSessionDidUnsetActiveSessionNotification;

Discussion:

NSNotificationCenter name indicating that an active session was unset

Declarado en: FBSession.h

Definiciones de tipo

FBSessionLoginBehavior enum

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

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

Constante	Descripción
`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

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 disalow fallback Facebook Login completely, or to force a fallback login.

Declarado en: FBSession.h

FBSessionReauthorizeResultHandler

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

typedef void (^FBSessionReauthorizeResultHandler)(
    FBSession *session, 
    NSError *error);

Declarado en: 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;

Constante	Descripción
`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

Declarado en: FBSession.h

FBSessionStateHandler

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

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

Declarado en: FBSession.h