Authentication

The authentication methods used in the Facebook iOS SDK. These methods are defined in Facebook.h.

You implement these methods to do the following:

• Initialize the Facebook instance with your app ID. Once initialized the instance can be used for follow-on method calls.

• Initiate the user authentication and app authorization flow. Once this is completed successfully you can make additional API calls that require the user authorization.

• Refresh the current access_token. The access_token is automatically refreshed when a Facebook API call is made but you may also want to manually do this for active users when your app is re-activated.

• Log out the user from Facebook.

• Handle the Single Sign-On URL (SSO) callback. This is part of the SSO implementation.

• Check if the user session is valid. You may do this to check if an access_token is valid so you can handle re-authenticating the user. You may also do this to expose functionality that requires the user to be logged in.

Instance Methods

---

initWithAppId:andDelegate:

Convenience method for initializing a Facebook instance.

- (id)initWithAppId:(NSString *)app_id
    andDelegate:(id<FBSessionDelegate>)delegate;

Parameters

app_id - The Facebook application id.

delegate - The receiver's delegate or nil if it doesn't have a delegate. See FBSessionDelegate for information on the delegate protocol.

Return Value

Newly initialized Facebook instance.

Notes

You must call this method before making any further calls to the Facebook API. You should set up your delegate to handle the any follow-on authorization callbacks using the newly created instance.

---

initWithAppId:urlSchemeSuffix:andDelegate:

Convenience method for initializing a Facebook instance.

- (id)initWithAppId:(NSString *)app_id
    urlSchemeSuffix:(NSString *)urlSchemeSuffix
    andDelegate:(id<FBSessionDelegate>)delegate;

Parameters

app_id - The Facebook application id.

urlSchemeSuffix - A string that will be appended to your base URL scheme for Single Sign-On flows. This parameter is useful in scenarios where you want to share a single Facebook app id across multiple apps.

delegate - The receiver's delegate or nil if it doesn't have a delegate. See FBSessionDelegate for information on the delegate protocol.

Return Value

Newly initialized Facebook instance.

Notes

You must call this method before making any further calls to the Facebook API. You should set up your delegate to handle the any follow-on authorization callbacks using the newly created instance.

---

authorize:

Starts the authorization flow for the user with the requested permissions.

- (void)authorize:(NSArray *)permissions;

Parameters

permissions - A list of the requested permissions. Pass an empty string if you do not wish to ask for permissions.

Notes

You call this method to prompt the user to log in to Facebook and grant the requested permissions to the application. Your current FBSessionDelegate delegate should be set up to handle the scenarios where the user grants or denies permissions, as well as any error scenarios.

---

extendAccessTokenIfNeeded

Attempts to extend the access_token.

- (void)extendAccessTokenIfNeeded;

Parameters

None.

Notes

The access_token expires after a certain amount of time and when you call this method it will be refreshed if it is still active and only after some time has passed since the last refresh. To ensure that you keep the access_token fresh for active users, call this method in your UIApplicationDelegate's applicationDidBecomeActive: method.

---

handleOpenURL:

Handles the processing of the URL used in the Single Sign-On (SSO) flow.

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

Parameters

url - The URL that was passed to the application delegate's handleOpenURL method.

Return Value

YES if the URL starts with fb[app_id]://authorize and hence was handled by SDK, NO otherwise.

Notes

You must call this method from your UIApplicationDelegate's handleOpenURL method. This ensures that the SSO flow is properly handled when the user is directed back to your app from Facebook application or Safari.

---

logout:

Invalidate the current user session.

- (void)logout:(id<FBSessionDelegate>)delegate;

Parameters

delegate - The receiver's delegate or nil if it doesn't have a delegate. See FBSessionDelegate for information on the delegate protocol.

Notes

This method does not unauthorized the application, it simply invalidates the access_token. The user can unauthorized the application through the app settings page on the Facebook website.

---

isSessionValid

Check if the access_token is available and has not expired.

- (BOOL)isSessionValid;

Parameters

None.

Return Value

YES if the access_token is valid, NO if it is invalid.