face book developer toolkit
TRANSCRIPT
Facebook Developer ToolkitDeveloped for Microsoft By Clarity Consulting Inc. - www.claritycon.com
Table Of Contents1 Leveraging the Facebook API in 5 minutes.........................................................................................4
1.1 Desktop Development.................................................................................................................4
1.2 Web Development.......................................................................................................................7
2 Pre-requisites....................................................................................................................................12
3 Introduction......................................................................................................................................12
4 Overview...........................................................................................................................................12
4.1 Facebook API Overview.............................................................................................................12
4.2 Using the FacebookService to Access the API............................................................................13
4.2.1 Infinite Sessions.................................................................................................................13
4.3 Facebook Desktop Development...............................................................................................13
4.4 Facebook Web Development.....................................................................................................14
4.5 Using LINQ.................................................................................................................................15
5 Detailed Class Design........................................................................................................................15
5.1 Facebook.Components..............................................................................................................15
5.1.1 FacebookService Class.......................................................................................................15
5.2 Facebook Data Objects..............................................................................................................30
5.2.1 Album Class........................................................................................................................30
5.2.2 Photo Class.........................................................................................................................32
5.2.3 FacebookEvent Class..........................................................................................................33
5.2.4 Group Class........................................................................................................................36
5.2.5 GroupUser Class.................................................................................................................38
5.2.6 User Class...........................................................................................................................39
5.2.7 SchoolHistory Class............................................................................................................43
5.2.8 HighSchool Class................................................................................................................43
5.2.9 HigherEducation Class........................................................................................................44
5.2.10 Network Class....................................................................................................................44
5.2.11 Location Class....................................................................................................................45
5.2.12 Work Class.........................................................................................................................46
6 Code Snippets...................................................................................................................................47
6.1 Windows Form: Application Setup............................................................................................47
6.2 Windows Form: Retrieving Friends............................................................................................47
6.3 Windows Form: Utilizing the FriendList Control........................................................................47
6.4 Windows Form: Hooking a FriendList Control to a Profile Control............................................48
6.5 Web Application: Authentication Process..................................................................................49
1 Leveraging the Facebook API in 5 minutes
1.1 Desktop Development Satisfy Pre-requisites described below Start a new Windows application project
o File – New – Projecto Windows Application
Visual C#
Visual Basic
Add the FacebookService component from the toolbox to the Form’s component tray
Provide the API Key and Secret values
Drag a FriendList from the toolbox onto the design surface for the form
Hook up the form Load Evento Find Load in the Event list in the property window, type Form_Load. Press Enter.
In the generated Form_Load method, set the Friends property of the FriendList control to the Collection returned by calling the GetFriends method of the FacebookService. As shown here:
Visual C# private void Form_Load(object sender, EventArgs e) { friendList1.Friends = FacebookService1.GetFriends(); }
Visual Basic
Private Overloads Sub OnLoad()
friendList1.Friends = FacebookService1.GetFriends() End Sub
Press F5 to run the application
1.2 Web Development Satisfy Pre-requisites described below In Visual Web Developer 2005 Express edition
o File – New – Web Site
Visual C#
Visual Basic
Switch to Design View of Default.aspx
On Default.aspx, drag a friendlist from the toolbox
Add the following code to the Default.aspx Configure the API key and secret
Visual C#public partial class _Default : Page {
Facebook.Components.FacebookService _fbService = new Facebook.Components.FacebookService();
protected void Page_Load(object sender, EventArgs e) { // ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "YOURKEYHERE"; _fbService.Secret = "YOURSECRETHERE";
Visual BasicPublic Partial Class _Default
Inherits PagePrivate _fbService As Facebook.Components.FacebookService = New Facebook.Components.FacebookService()
Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
' ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "YOURKEYHERE"
_fbService.Secret = "YOURSECRETHERE" Set the IsDesktopApplication property of the FacebookService component
Visual C#_fbService.IsDesktopApplication = false;
Visual Basic_fbService.IsDesktopApplication = False
Check if we have already stored the Facebook session information or if the auth_token is in the query params. We will store what we know about the current user’s Facebook Session in a server side variable. We will then check that variable to see if we already have established a Facebook session on behalf of the current user. Visual C#
string sessionKey = Session["Facebook_session_key"] as String; string userId = Session["Facebook_userId"] as String;
// When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params
string authToken = Request.QueryString["auth_token"];
Visual BasicDim sessionKey As String =
TryCast(Session("Facebook_session_key"), String)Dim userId As String = TryCast(Session("Facebook_userId"), String)
' When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params
Dim authToken As String = Request.QueryString("auth_token")
If we have an established session, set it into our instance of the service
Visual C# if (!String.IsNullOrEmpty(sessionKey))
{ _fbService.SessionKey = sessionKey; _fbService.UserId = userId; }
Visual Basic
' We have already established a session on behalf of this userIf (Not String.IsNullOrEmpty(sessionKey)) Then
_fbService.SessionKey = sessionKey_fbService.UserId = userId
If not, check if we have the auth_token in the query params. If we do, it means we just got called from the Facebook login page.
Visual C# else if (!String.IsNullOrEmpty(authToken))
{ _fbService.CreateSession(authToken); Session["Facebook_session_key"] = _fbService.SessionKey; Session["Facebook_userId"] = _fbService.UserId; Session["Facebook_session_expires"] = _fbService.SessionExpires; }
Visual Basic
' This will be executed when Facebook login redirects to our pageElseIf (Not String.IsNullOrEmpty(authToken)) Then
_fbService.CreateSession(authToken)Session("Facebook_session_key") = _fbService.SessionKeySession("Facebook_userId") = _fbService.UserIdSession("Facebook_session_expires") =
_fbService.SessionExpires
If neither, we need to redirect the user to the Facebook hosted login page
Visual C# else
{ Response.Redirect(@"http://www.Facebook.com/login.php?api_key=" + _fbService.ApplicationKey + @"&v=1.0"); }
Visual BasicElse
Response.Redirect("http://www.Facebook.com/login.php?api_key=" & _fbService.ApplicationKey & "&v=1.0")
End If
Set the friends property of the friendlist
Visual C# if (!IsPostBack)
{ // Use the FacebookService Component to populate Friends
MyFriendList.Friends = _fbService.GetFriends(); }
Visual BasicIf (Not IsPostBack) Then
' Use the FacebookService Component to populate FriendsMyFriendList.Friends = _fbService.GetFriends()
End If
2 Pre-requisitesFirst, you download one of the Visual Studio Express products . To develop a desktop application, you can use Visual C# 2005 Express Edition (or later) or Visual Basic 2005 Express Edition (or later). If you want to build a web application, you can use Visual Web Developer 2005 Express Edition (or later).
Next, in order to use the Facebook API, you must first register for a developer account with Facebook at http://developers.Facebook.com/account.php. You will need to specify whether your application is a Website or a Desktop application. After registering for your developer account, you will receive and API key and secret. These are critical for using the Facebook API and you should keep this readily available
3 IntroductionThis document outlines the components and controls that are available for to help simplify development against the Facebook API. The main component is the FacebookService component. The FacebookService wraps the Facebook API and provides an easy to use interface for calling the different methods currently available in the 1.0 version of the Facebook API. In addition, some Windows and web controls were installed which will provide a quick way to start leveraging the Facebook data in your application. We’ve also provided you with some cool fun samples. These can be found in <INSERT DIRECTORY HERE>. Additionally, we’ve provide all the source code for the API, components, controls and samples for you to explore.
4 OverviewAll of the sections below assume that the developer has signed up for a Facebook developer account and received an API key and secret from Facebook.
4.1 Facebook API OverviewThe Facebook API is a REST interface allowing applications to post a specific HTTP address and receive structured XML representing the requested Facebook data. The 1.0 version of the API contains primarily Get operations, and does not provide personal or contact information for Facebook users. The only Set type operations that are available are CreateAlbum, UploadPhoto and AddTag.
For more information on the available functions, see the API documentation at http://developers.Facebook.com/documentation.php?v=1.0
4.2 Using the FacebookService to Access the APIThe Facebook.dll that was installed at %Program Files%\Coding4Fun\Facebook\Binaries contains the FacebookService component. This component contains all the methods that wrap the available API calls. To use this component, each application must programmatically set their application key and secret. For specifics on interacting with the FacebookService see the Desktop and Web Development below. The methods within the FacebookService return strongly typed data objects representing the data. These objects are intended to simplify the developer experience using the API.
4.2.1 Infinite SessionsThe Facebook API supports Infinite Sessions. What this means is that users of custom developed Facebook desktop applications have the ability to save their credentials and not be required to login to the application on subsequent uses. In order for an application to take advantage of infinite sessions, the application should check SessionExpires property of the Facebook Service after a Session is initiated. If this property is false, the application can store the userId and SessionKey that are associated with the user and set them on the FacebookService whenever this user returns.
4.3 Facebook Desktop DevelopmentTo start utilizing the Facebook API, you will need to add the FacebookService component to your project. To do this just drag an instance of FacebookService from the toolbox onto the component tray and enter your API Key and Secret.
The FacebookService component contains methods that wrap all of the methods of the Facebook API. The following provides an example for getting all the friends of the logged in user. This method returns a generic collection of User objects. The User object is a strongly typed representation of a Facebook User profile.
Visual C#
using System.Collections.Generic;using System.Collections.ObjectModel;…
Collection<User> friends = FacebookService1.GetFriends();
Visual Basic
Imports System.Collections.GenericImports System.Collections.ObjectModel… Dim friends As Collection(Of User) = FacebookService1.GetFriends()
4.4 Facebook Web DevelopmentThe authentication process for a Web Application is more involved than for a Windows application. When the developer account is setup, the developer must choose whether their application is a Web application or Desktop application. In the case of a web application, the developer must specify a return url. This is the url that users of the web application will be redirected to after logging in on the Facebook hosted login page. For the sample web site, it is setup to return to http://localhost/FacebookWebSample/default.aspx. To run and debug the FacebookWebSample project, you must configure your Visual Studio Web Project to start your web application using this address. Because of this requirement, the simplest way to configure to run the WebSample is using IIS. (Since it runs on port 80 and handles addresses like the above)
1. Create an IIS Virtual Directory called FacebookWebSample pointed at the location of your FacebookWebSample.
2. Set the Web Project to start using this website. a. Right Click FacebookWebSample in Visual Studio – Select Property Pagesb. Select Start Optionsc. Click Start URL radio button – Enter http://localhost/FacebookWebSample/default.aspx
3. Write code to handle 3 states. a. If we don’t have an auth_token, redirect to the Facebook hosted login page.b. If we have an auth_token, start a session on behalf of the user.c. Store the user’s session information for making calls to the Facebook service.
See the Code Snippets section for more details.
4.5 Using LINQThe toolkit contains some sample code showing (both a web application and Windows application version) how LINQ and Orcas can be used to provide a richer set of development features against the Facebook API data. The samples included will only work in “Orcas” (the codename for the next version of Visual Studio) and show how we can right code using a syntax similar to SQL to filter and search through the friends that are returned from Facebook. The samples leverage LINQ over XML and run the filtering directly against the returned XML. Alternatively, the LINQ code could just as easily have been written against the Generic Collections returned by the our toolkit. For more information on LINQ, check out http://msdn2.microsoft.com/en-us/netframework/aa904594.aspx. If you want to download Orcas and try out LINQ and the enclosed samples, you can do so here, http://msdn.microsoft.com/vstudio/express/future.
The source for these samples is installed to C:\Program Files\Coding4Fun\Facebook\LINQ Samples
5 Detailed Class Design
5.1 Facebook.Components
5.1.1 FacebookService ClassThis class contains methods that wrap the Facebook API and return strongly typed objects representing Facebook data. Additionally, this class has functionality to encapsulate the Facebook login process for both Microsoft Windows-based clients and ASP.NET web based clients.
Figure 1: FacebookService Class
5.1.1.1 Property: ApplicationKeyThis property is required to be set by all consuming applications. This property should be set to the API key acquired from Facebook when developer signed up for a Facebook developer account.
Definition: public string ApplicationKey
5.1.1.2 Property: IsDesktopApplicationThis property is an indicator used to determine if the consuming application is a desktop (Windows) or web based application. This is needed because the application secret is handled differently for Windows and web applications.
Definition: public bool IsDesktopApplication
5.1.1.3 Property: SecretThis property is required to be set by all consuming applications. This is the secret used to encrypt parameters passed to the Facebook API. For web applications, the secret is constant and set at the beginning of interaction with the service. For Windows applications, an initial secret is required to establish a session, but a new secret is acquired that coincides with each session.
Definition: public string Secret
5.1.1.4 Property: SessionExpiresThis property is an indicator of whether the current session is an infinite session or not. The value is determined after a user of the consuming application logs in on the Facebook hosted web page. Consuming applications can leverage an infinite session by storing the session information locally and by passing the logon process in subsequent interactions with the user.
Definition: public bool SessionExpires
5.1.1.5 Property: SessionKeyThis property stores the session key for the current user session. This can either be set by the consuming application (which would typically be done when the consuming application recognizes a user that has an infinite session established) or will be set by the FacebookService after the logon process is complete
Definition: public string SessionKey
5.1.1.6 Property: UserIdThis property is stored the Facebook userid. Similar to the SessionKey, in the case of infinite sessions the comsuming application will set this property with the known UserId, otherwise this property will be set by the logon process.
Definition: public string ApplicationKey
5.1.1.7 Method: AddTagThis method wraps the Facebook API method photos.addTag. This method is used to add tags to any “pending” photos. A pending photo is a photo that has been uploaded but not yet confirmed.
Definition: public void AddTag(string photoId, string tagText, string tagUserId, int xCoord, int yCoord)
Parameters:
Parameter Description
photoId The Facebook identifier of the pending photo to be tagged
tagText The message that should be associated with the tag. Use this OR tag User Id. Not both.
tagUserId The Facebook userid of the person the tag points to
xCoord The X coord (in pixels) where the tag should begin in the specified picture
yCoordThe Y coord (in pixels) where the tag should begin in the specified picture
Return Type: N/A
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshhold
5.1.1.8 Method: AreFriendsThis method wraps the Facebook API method friends.areFriends. This method is used to determine if two Facebook users are friends or not.
Definition (1): public bool AreFriends(string userId1, string userId2)
Definition (2): public bool AreFriends(User user1, User user2)
Parameters (1):
Parameter Description
userId1 The Facebook identifier of the first user
userId2 The Facebook identifier of the second user
Parameters (2):
Parameter Description
user1The a strongly typed instance of a User representing the first Facebook user
user2 The a strongly typed instance of a User representing the second Facebook user
Return Type: bool: true if 2 users are currently Facebook friends, otherwise false.
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.9 Method: ConnectToFacebookThis method is not typically used by the consuming application. The FacebookService will check if there is a valid session that it can use to make API calls, if not it will invoke the ConnectToFacebook method. This method is only needed by desktop applications and uses a hosted web browser to allow the user to login to the Facebook hosted login page.
Definition: public void ConnectToFacebook()
Parameters:
Parameter Description
None None
Return Type: N/A
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.10 Method: CreateSessionThis method has a public version and a private version. The private version is used for Windows applications and is called from ConnectToFacebook. The public version takes in an auth token and is used by web based applications. Web based applications get the auth token as a url parameter after the user logins on the Facebook hosted webpage. The web application then needs to start the session using this method and passing in the auth token.
Definition (1): private void CreateSession()
Definition (2): public void CreateSession(string authToken)
Parameters (1):
Parameter Description
none None
Parameters (2):
Parameter Description
authToken The authentication token returned to the web application from the Facebook login page.
Return Type: N/A
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.11 Method: GetEventMembersThis method wraps the Facebook API method events.getMembers. This method is used to return all the users that have been invited to an event and their current rsvp status.
Definition: public Collection<EventUser> GetEventMembers(string eventId)
Parameters:
Parameter Description
eventId The Facebook identifier of the event
Return Type: Collection<EventUser>: A collection of EventUser. EventUser is a simple wrapper to the User class that adds RSVP status.
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.12 Method: GetEventsThis method wraps the Facebook API method events.get. This method is used to retrieve event information. There are overrides supporting get by event id, user id and date.
Definition (1): public Collection<FacebookEvent> GetEvents()
Definition (2): public Collection<FacebookEvent> GetEvents(string userId)
Definition (3): public Collection<FacebookEvent> GetEvents(Collection<string> eventList)
Definition (4): public Collection<FacebookEvent> GetEvents(Collection<string> eventList, string userId)
Definition (5): public Collection<FacebookEvent> GetEvents(Collection<string> eventList, string userId, DateTime? startDate, DateTime? endDate)
Parameters (1):
Parameter Description
None Get Events that the logged in user is invited to
Parameters (2):
Parameter Description
userId The Facebook userId that events are retrieved for. Will return all events this person is invited to.
Parameters (3):
Parameter Description
eventList A collection of eventIds. Will return the event information for each event matching an event id passed in.
Parameters (4):
Parameter Description
userId The Facebook userId that events are retrieved for. Will return events this person is invited to that are also specified in the eventList.
eventListA collection of eventIds. Will return the event information for each event matching an event id passed in that has the specified UserId invited.
Parameters (5):
Parameter Description
userId The Facebook userId that events are retrieved for. Will return events this person is invited to that are also specified in the eventList.
eventList A collection of eventIds. Will return the event information for each event matching an event id passed in that has the specified UserId
invited.
startDate Only retrieve events matching the above criteria and starting after this date.
endDateOnly retrieve events matching the above criteria and ending before this date.
Return Type: Collection<FacebookEvent>
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.13 Method: GetFriendsThis method wraps the Facebook API method friends.get. This method is used to get all the friends of the logged in user.
Definition: public Collection<User> GetFriends()
Parameters:
Parameter Description
none Get friends of the logged in user
Return Type: Collection<User>: A collection of populated user objects representing each of the logged in user’s friends.
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.14 Method: GetFriendsAppUsersThis method wraps the Facebook API method friends.getAppUsers. This method is used to get all the friends of the logged in user that are also users of this consuming application.
Definition: public Collection<User> GetFriendsAppUsers()
Parameters:
Parameter Description
none Get friends of the logged in user that are users of this application
Return Type: Collection<User>: A collection of populated user objects representing each of the logged in user’s friends that are also users of this application.
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.15 Method: GetGroupMembersThis method wraps the Facebook API method groups.getMembers. This method is to retrieve profile information about all Facebook users that are members of a particular group.
Definition: public Collection<GroupUser> GetGroupMembers(string groupId)
Parameters:
Parameter Description
groupId The Facebook identifier of the group
Return Type: Collection<GroupUser> - GroupUser is a lightweight wrapper to user that adds a property for the users position in the group
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.16 Method: GetGroupsThis method wraps the Facebook API method groups.get. This method is used to retrieve the groups matching a specific criteria.
Definition (1): public Collection<Group> GetGroups()
Definition (2): public Collection<Group> GetGroups(string userId)
Definition (3): public Collection<Group> GetGroups(Collection<string> groupsList)
Definition (4): public Collection<Group> GetGroups(string userId, Collection<string> groupsList)
Parameters (1):
Parameter Description
None Get all groups for the logged in user
Parameters (2):
Parameter Description
userId The Facebook userId to return groups for
Parameters (3):
Parameter Description
groupListA collection of group ids. Return all groups matching a group id in the list.
Parameters (4):
Parameter Description
userId The Facebook userId to return groups for
groupList A collection of group ids. Return all groups matching a group id in the list.
Return Type: Collection<Group>
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.17 Method: GetPhotoAlbumsThis method wraps the Facebook API method photos.getAlbums. This method is used to get photo album details based on search criteria
Definition (1): public Collection<Album> GetPhotoAlbums()
Definition (2): public Collection<Album> GetPhotoAlbums(string userId)
Definition (3): public Collection<Album> GetPhotoAlbums(Collection<string> albumList)
Definition (4): public Collection<Album> GetPhotoAlbums(string userId, Collection<string> albumList)
Parameters (1):
Parameter Description
None Get all albums for the logged in user
Parameters (2):
Parameter Description
userId Facebook userid to retrieve all albums for
Parameters (3):
Parameter Description
albumList Collection of Facebook album ids to retrieve
Parameters (4):
Parameter Description
userId Facebook userid to retrieve albums for
albumList Collection of Facebook album ids to retrieve
Return Type: Collection<Album>
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.18 Method: GetPhotosThis method wraps the Facebook API method photos.get. This method is used to get photos based on search criteria.
Definition (1): public Collection<Photo> GetPhotos(string albumId)
Definition (2): public Collection<Photo> GetPhotos(Collection<string> photoList)
Definition (3): public Collection<Photo> GetPhotos(string albumId, Collection<string> photoList)
Parameters (1):
Parameter Description
albumId The Facebook identifier of the album to retrieve photos for
Parameters (2):
Parameter Description
photoList Collection of Facebook photo identifier to return information about
Parameters (3):
Parameter Description
albumId The Facebook identifier of the album to retrieve photos for
photoList Collection of Facebook photo identifier to return information about
Return Type: Collection<Photo>
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.19 Method: GetTagsThis method wraps the Facebook API method photos.getTags. This method is used to retrieve all tags for a particular photo.
Definition: public Collection<PhotoTag> GetTags(Collection<string> photoList)
Parameters:
Parameter Description
photoList Collection of Facebook photo identifiers to return tags for
Return Type: Collection<PhotoTag>
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.20 Method: GetUserInfoThis method wraps the Facebook API method users.getInfo. This method is used to retrieve profile information for a set of users.
Definition(1): public User GetUserInfo()
Definition(2): public Collection<User> GetUserInfo(string userIds)
Parameters(1):
Parameter Description
none Get the user profile for the logged in user
Parameters(2):
Parameter Description
userIds Comma separated list of Facebook user identifiers
Return Type: User
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.1.1.21 Method: UploadPhotoThis method wraps the Facebook API method photos.upload. This method is used to upload a new photo. The uploaded photo will be considered pending until the user utilizes the website to confirm the photo.
Definition: public void UploadPhoto(string albumId, FileInfo uploadFile)
Parameters:
Parameter Description
albumId The album identifier to upload the photo to. If null, then will upload to default album
uploadFile File containing the photo to upload.
Return Type: N/A
Exceptions:
FacebookException: This base class of all exceptions. If exception could not be classified, FacebookException will be used.
FacebookInvalidUserException: The user that the call was made on behalf of is not valid.
FacebookRequestLimitException: Indicates that the consuming application has made too many Facebook API calls in short period of time.
FacebookServiceUnavailableException: Indicates that the website used to host the Facebook REST client was not available.
FacebookSigningException: Indicates that the secret or API key were not specified or were invalid.
FacebookTimeoutException: Indicates that the Facebook API did not respond in a within the timeout threshold
5.2 Facebook Data Objects
5.2.1 Album ClassThis class represents a Facebook photo album.
5.2.1.1 Property: AlbumIdThe Facebook identifier of the album
Definition: public string AlbumId
5.2.1.2 Property: CoverPhotoIdThe Facebook identifier of photo that is used as the cover photo for the album
Definition: public string CoverPhotoId
5.2.1.3 Property: CreateDateThe date that the album was created
Definition: public DateTime CreateDate
5.2.1.4 Property: DescriptionThe user entered description of the album
Definition: public string Description
5.2.1.5 Property: LocationThe location that the album pertains to
Definition: public string Location
5.2.1.6 Property: ModifiedDateThe date that this album was last updated
Definition: public DateTime ModifiedDate
5.2.1.7 Property: NameThe name of the album
Definition: public string Name
5.2.1.8 Property: OwnerUserIdThe Facebook user id of the person who created the album
Definition: public string OwnerUserId
5.2.2 Photo ClassThis class contains the information about a Facebook Photo.
5.2.2.1 Property: AlbumIdA Facebook unique identifier of the album that the photo is part of.
Definition: public string AlbumId
5.2.2.2 Property: CaptionThe caption of the photo.
Definition: public string Caption
5.2.2.3 Property: CreateDateA date when the photo was first uploaded.
Definition: public DateTime CreateDate
5.2.2.4 Property: LinkThe photo link.
Definition: public Uri Link
5.2.2.5 Property: OwnerUserIdA Facebook unique identifier of user who owns the photo.
Definition: public string OwnerUserId
5.2.2.6 Property: PhotoIdA Facebook unique identifier of the photo.
Definition: public string PhotoId
5.2.2.7 Property: PictureThe actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit.
Definition: public Image Picture
5.2.2.8 Property: PictureUrlThe url of this picture
Definition: public Uri PictureUrl
5.2.3 FacebookEvent ClassThis class represents a Facebook event.
5.2.3.1 Property: CreatorThe Facebook identifier of the user who created the event
Definition: public string Creator
5.2.3.2 Property: DescriptionDescription of the event
Definition: public string Description
5.2.3.3 Property: EndDateThe date that the events ends
Definition: public DateTime EndDate
5.2.3.4 Property: EventIdThe Facebook identifier of the event.
Definition: public string EventId
5.2.3.5 Property: HostThe Facebook user id of the host of the event
Definition: public string Host
5.2.3.6 Property: LocationThe name of the place where the event will take place.
Definition: public string Location
5.2.3.7 Property: NameThe name of the event
Definition: public string Name
5.2.3.8 Property: NetworkIdThe Facebook identifier of the network that this event is a part of
Definition: public string NetworkId
5.2.3.9 Property: PictureThe actual image associated with the event. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit.
Definition: public Image Picture
5.2.3.10 Property: PictureUrlThe url of this event’s picture
Definition: public Uri PictureUrl
5.2.3.11 Property: StartDateThe date and time when the event starts
Definition: public DateTime StartDate
5.2.3.12 Property: SubTypeThe seconary group of event type.
Definition: public string SubType
5.2.3.13 Property: TagLineThe tagline of the event if one was specified
Definition: public string TagLine
5.2.3.14 Property: TypeThe primary grouping of the event
Definition: public string Type
5.2.3.15 Property: UpdateDateThe Facebook user id of the person who created the album
Definition: public DateTime UpdateDate
5.2.4 Group ClassThis class contains represents a Facebook group.
5.2.4.1 Property: CreatorThe Facebook identifier of the user who created the group
Definition: public string Creator
5.2.4.2 Property: DescriptionThe description of the group
Definition: public string Description
5.2.4.3 Property: GroupIdThe Facebook identifier of the group
Definition: public string GroupId
5.2.4.4 Property: NameThe user entered name of the group
Definition: public string Name
5.2.4.5 Property: NetworkIdThe Facebook identifier of the network that the group is part of
Definition: public string NetworkId
5.2.4.6 Property: OfficeThe address of the group’s office if it has one.
Definition: public string Office
5.2.4.7 Property: PictureThe actual image associated with the group. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit.
Definition: public Image Picture
5.2.4.8 Property: PictureUrlThe url of this group’s picture
Definition: public Uri PictureUrl
5.2.4.9 Property: RecentNewsFree form text describing recent news associated with the group
Definition: public string Recent News
5.2.4.10 Property: SubTypeThe seconary group of group type.
Definition: public string SubType
5.2.4.11 Property: TypeThe primary grouping of the event
Definition: public string Type
5.2.4.12 Property: UpdateDateThe last date and time that changes were made to the group
Definition: public DateTime UpdateDate
5.2.4.13 Property: VenueThe name of the venue where the group meetings occur
Definition: public string Venue
5.2.4.14 Property: WebSiteThe url of the website for the group.
Definition: public string WebSite
5.2.5 GroupUser ClassThis class contains represents a Facebook group.
5.2.5.1 Property: GroupIdThe Facebook identifier of the group
Definition: public string GroupId
5.2.5.2 Property: PositionsCollection of positions held by this user
Definition: public Collection<GroupPosition> Positions
5.2.5.3 Property: UserThe user object representing the profile of the user
Definition: public User User
5.2.5.4 Property: UserIdThe Facebook identified of the user
Definition: public string UserId
5.2.6 User ClassThis class contains represents a Facebook user.
5.2.6.1 Property: AboutMeA string describing the user. Free form.
Definition: public string AboutMe
5.2.6.2 Property: ActivitiesFree form text describing the activities this user is interested in.
Definition: public string Activities
5.2.6.3 Property: AffiliationsA collection of Networks this user belongs to
Definition: public Collection<Network> Affiliations
5.2.6.4 Property: BirthdayThe day this user was born
Definition: public DateTime? Birthday
5.2.6.5 Property: BooksFree form text describing this user’s favorite books
Definition: public string Books
5.2.6.6 Property: CurrentLocationThe current location for the user
Definition: public Location CurrentLocation
5.2.6.7 Property: FirstNameThe user’s first name
Definition: public string FirstName
5.2.6.8 Property: HometownLocationThe location of the user’s hometown
Definition: public Location HometownLocation
5.2.6.9 Property: InterestedInGendersA collection containing enum values representing the genders that this person is interested in.
Definition: public Collection<Gender> InterestedInGenders
5.2.6.10 Property: InterestsFree form text describing the user’s interests
Definition: public string Interests
5.2.6.11 Property: InterestedInRelationshipTypesA collection containing enum values representing the types of relationships that this person is interested in.
Definition: public Collection<LookingFor> InterstedInRelationshipTypes
5.2.6.12 Property: LastNameThe user’s last name
Definition: public string LastName
5.2.6.13 Property: MoviesFree form text describing the user’s favorite movies
Definition: public string Movies
5.2.6.14 Property: MusicFree form text describing the user’s favorite music
Definition: public string Music
5.2.6.15 Property: NameThe user’s name
Definition: public string Name
5.2.6.16 Property: NotesCountThe number of notes this user has associated with their Facebook account.
Definition: public int NotesCount
5.2.6.17 Property: PictureThe actual image associated with this user’s profile. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit.
Definition: public Image Picture
5.2.6.18 Property: PictureUrlThe url of this user’s Facebook picture
Definition: public Uri PictureUrl
5.2.6.19 Property: PoliticalViewAn enum value representing the user’s political view
Definition: public PoliticalView PoliticalView
5.2.6.20 Property: QuotesFree form text representing the user’s favorite quotes
Definition: public string Quotes
5.2.6.21 Property: RelationshipStatusAn enum value representing the user’s current relationship status.
Definition: public RelationshipStatus RelationshipStatus
5.2.6.22 Property: ReligionFree form text representing the Religion
Definition: public string Religion
5.2.6.23 Property: SchoolHistoryA data object representing the user’s education history
Definition: public SchoolHistory SchoolHistory
5.2.6.24 Property: SexThe user’s gender
Definition: public Gender Sex
5.2.6.25 Property: SignificantOtherIdThe Facebook user id of this user’s significant other
Definition: public string SignificantOtherId
5.2.6.26 Property: TVShowsFree form text describing this user’s favorite TVShows
Definition: public string TVShows
5.2.6.27 Property: UserIdThe Facebook unique identifier of the user
Definition: public string UserId
5.2.6.28 Property: WallCountThe number of messages that have been written on this user’s wall.
Definition: public int WallCount
5.2.6.29 Property: RelationshipStatusThe Facebook identified of the user
Definition: public RelationshipStatus RelationshipStatus
5.2.6.30 Property: WorkHistoryCollection of Work object representing this user’s employment history
Definition: public Collection<Work> WorkHistory
5.2.7 SchoolHistory ClassThis class contains Facebook user’s education history (including high school and college).
5.2.7.1 Property: HigherEducatonA collection of HigherEducation object representing the colleges this user attended.
Definition: public Collection<HigherEducation> HigherEducation
5.2.7.2 Property: HighSchoolA HighSchool data object containing information about the high schools this user attended.
Definition: public HighSchool HighSchool
5.2.8 HighSchool ClassThis classs contains information about the high schools this user attended.
5.2.8.1 Property: GraduationYearThe year this user graduated from college
Definition: public int GraduationYear
5.2.8.2 Property: HighSchoolOneIdThe Facebook unique identifier of the high school
Definition: public string HighSchoolOneId
5.2.8.3 Property: HighSchoolOneNameThe name of the high school
Definition: public string HighSchoolOneName
5.2.8.4 Property: HighSchoolTwoIdThe Facebook unique identifier of the high school
Definition: public string HighSchoolTwoId
5.2.8.5 Property: HighSchoolTwoNameThe name of the high school
Definition: public string HighSchoolTwoName
5.2.9 HigherEducation ClassThis class contains Facebook user’s college education history.
5.2.9.1 Property: AttendedForAn enum value representing if the school was attended for under graduate work or graduate work
Definition: public SchoolType AttendedFor
5.2.9.2 Property: ClassYearGraduation year
Definition: public int ClassYear
5.2.9.3 Property: ConcentrationA collection describing user’s majors
Definition: public Collection<string> Concentration
5.2.9.4 Property: SchoolThe name of the school
Definition: public string School
5.2.10 Network ClassThis class contains the information about a Facebook Network.
5.2.10.1 Property: NameThe name of the network.
Definition: public string Name
5.2.10.2 Property: NetworkIdThe Facebook unique identifier of the network.
Definition: public string NetworkId
5.2.10.3 Property: StatusThe status of the network (Open or Closed).
Definition: public string Status
5.2.10.4 Property: TypeAn enum value representing the type of the network (College, High School, Work or Region)
Definition: public NetworkType Type
5.2.10.5 Property: YearThe year associated with the network.
Definition: public int Year
5.2.11 Location ClassThis class contains information about a geographic location.
5.2.11.1 Property: CityA city of the location.
Definition: public string City
5.2.11.2 Property: CountryA country of the location.
Definition: public Country Country
5.2.11.3 Property: StateA state of the location.
Definition: public State State
5.2.11.4 Property: StateAbbreviationA postal abbreviation of the state of the location.
Definition: public StateAbbreviation StateAbbreviation
5.2.11.5 Property: ZipCodeA zip code of the location.
Definition: public string ZipCode
5.2.12 Work ClassThis class contains Facebook user’s work history.
5.2.12.1 Property: CompanyNameThe name of the company.
Definition: public string CompanyName
5.2.12.2 Property: DescriptionThe description of job.
Definition: public string Description
5.2.12.3 Property: EndDateThe date that the user ended this employment.
Definition: public DateTime EndDate
5.2.12.4 Property: LocationThe location of the job.
Definition: public Location Location
5.2.12.5 Property: PositionThe user’s position/title.
Definition: public string Position
5.2.12.6 Property: StartDateThe date the user started the job.
Definition: public DateTime StartDate
6 Code Snippets
6.1 Windows Form: Application SetupAfter registering your desktop application at http://api.Facebook.com, you will receive an API key and a secret. To start utilizing the Facebook API, you must add a reference to the Facebook.dll. Drag an instance of FacebookService from the toolbox. Enter your API Key and Secret.
6.2 Windows Form: Retrieving FriendsThe FacebookService component contains methods that wrap all of the methods of the Facebook Developer API. The following provides an example for getting all the friends of the logged in user. This method returns a generic collection of User objects. The User object is a strongly typed representation of a Facebook User profile.
Visual C#using System.Collections.Generic;using System.Collections.ObjectModel;…
Collection<User> friends = FacebookService1.GetFriends();
Visual Basic
Imports System.Collections.GenericImports System.Collections.ObjectModel…
Dim friends As Collection(Of User) = FacebookService1.GetFriends()
6.3 Windows Form: Utilizing the FriendList ControlThere are several WinForm controls that exercise the FacebookService. This sample shows how to use the FriendList control. Drag a FriendList from the Toolbox to your form. (This assumes you have already added the FacebookService component and set your API key and secret). Simply set the Friends property of the FriendList control.
Visual C#using System.Collections.Generic;using System.Collections.ObjectModel;using Facebook.Controls;
…
friendList1.Friends = FacebookService1.GetFriends();
Visual Basic
Imports System.Collections.GenericImports System.Collections.ObjectModelImports Facebook.Controls…
friendList1.Friends = FacebookService1.GetFriends()
6.4 Windows Form: Hooking a FriendList Control to a Profile ControlThe Profile Control is used to display the detailed profile information about a Facebook User. This sample shows how to hook up the event that a Friend was selected in the FriendList Control and populate a Profile control on the same form.
Visual C#using System.Collections.Generic;using System.Collections.ObjectModel;using Facebook.Controls;
…
Collection<User> friends = FacebookService1.GetFriends();
friendList1.Friends = friends;profile1.User = friends[0];friendList1.FriendSelected += new EventHandler<FriendSelectedEventArgs>(friendList1_FriendSelected);
…void friendList1_FriendSelected(object sender, FriendSelectedEventArgs e)
{ profile1.User = e.User; }
Visual Basic
Dim friends As Collection(Of User) = FacebookService1.GetFriends() friendList1.Friends = friends profile1.User = friends(0) AddHandler friendList1.FriendSelected, AddressOf friendList1_FriendSelected…
Private Sub friendList1_FriendSelected(ByVal sender As Object, ByVal e As FriendSelectedEventArgs)
profile1.User = e.UserEnd Sub
6.5 Web Application: Authentication ProcessWeb Application development requires writing code to handle 3 userstates.
1. If we don’t have an auth_token, redirect to the Facebook hosted login page.2. If we have an auth_token, start a session on behalf of the user.3. Store the user’s session information for making calls to the Facebook service.
The following shows a simple page that handles these 3 states.
Visual C#
// ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "bfeefa69afdfe81975f0d6136ace3009"; _fbService.Secret = "9b672d682e1d8befd06382953fc2615b"; _fbService.IsDesktopApplication = false;
string sessionKey = Session["Facebook_session_key"] as String; string userId = Session["Facebook_userId"] as String;
// When the user uses the Facebook login page, the redirect back here // will will have the auth_token in the query params
string authToken = Request.QueryString["auth_token"];
// We have already established a session on behalf of this user if (!String.IsNullOrEmpty(sessionKey)) { _fbService.SessionKey = sessionKey; _fbService.UserId = userId; } // This will be executed when Facebook login redirects to our page else if (!String.IsNullOrEmpty(authToken)) { _fbService.CreateSession(authToken); Session["Facebook_session_key"] = _fbService.SessionKey; Session["Facebook_userId"] = _fbService.UserId; Session["Facebook_session_expires"] = fbService.SessionExpires; } // Need to login else {
Response.Redirect(@"http://www.Facebook.com/login.php?api_key=" + _fbService.ApplicationKey + @"&v=1.0\");
}
if (!IsPostBack) { // Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends();
}
Visual Basic
Private _fbService As Facebook.Components.FacebookService = New Facebook.Components.FacebookService()
Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
' ApplicationKey and Secret are acquired when you sign up for _fbService.ApplicationKey = "7a399eeba47b0f5b2bfd88cc872ada4a" _fbService.Secret = "fad3d3fbeb8571957c39e2792073b978"
_fbService.IsDesktopApplication = False
Dim sessionKey As String = TryCast(Session("Facebook_session_key"), String)
Dim userId As String = TryCast(Session("Facebook_userId"), String)
' When the user uses the Facebook login page, the redirect back here will will have the auth_token in the query params
Dim authToken As String = Request.QueryString("auth_token")
' We have already established a session on behalf of this userIf (Not String.IsNullOrEmpty(sessionKey)) Then
_fbService.SessionKey = sessionKey_fbService.UserId = userId
' This will be executed when Facebook login redirects to our pageElseIf (Not String.IsNullOrEmpty(authToken)) Then
_fbService.CreateSession(authToken)Session("Facebook_session_key") = _fbService.SessionKeySession("Facebook_userId") = _fbService.UserIdSession("Facebook_session_expires") =
_fbService.SessionExpires' Need to loginElse
Response.Redirect("http://www.Facebook.com/login.php?api_key=" & _fbService.ApplicationKey & "&v=1.0")
End If
If (Not IsPostBack) Then' Use the FacebookService Component to populate FriendsMyFriendList.Friends = _fbService.GetFriends()
End If