Face Book Developer Toolkit

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

http://developers.facebook.com/documentation.php?v=1.0

http://en.wikipedia.org/wiki/REST

http://developers.facebook.com/account.php

http://msdn.microsoft.com/vstudio/express/downloads

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

http://localhost/FacebookWebSample/default.aspx

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.

http://msdn.microsoft.com/vstudio/express/future

http://msdn2.microsoft.com/en-us/netframework/aa904594.aspx

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.

http://developers.f8.facebook.com/documentation.php?v=1.0&method=friends.areFriends

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):

http://developers.f8.facebook.com/documentation.php?v=1.0&method=friends.areFriends


userId1 The Facebook identifier of the first user

userId2 The Facebook identifier of the second user

Parameters (2):


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:






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:


None None

Return Type: N/A

Exceptions:







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):


none None

Parameters (2):


authToken The authentication token returned to the web application from the Facebook login page.

Return Type: N/A

Exceptions:







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:


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:







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.

http://developers.f8.facebook.com/documentation.php?v=1.0&method=events.get

http://developers.f8.facebook.com/documentation.php?v=1.0&method=events.getMembers

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):


None Get Events that the logged in user is invited to

Parameters (2):


userId The Facebook userId that events are retrieved for. Will return all events this person is invited to.

Parameters (3):


eventList A collection of eventIds. Will return the event information for each event matching an event id passed in.

Parameters (4):


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):


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:







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:


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:



http://developers.f8.facebook.com/documentation.php?v=1.0&method=friends.get





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:


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:







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)

http://developers.f8.facebook.com/documentation.php?v=1.0&method=groups.getMembers

http://developers.f8.facebook.com/documentation.php?v=1.0&method=friends.getAppUsers

Parameters:


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:







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):


None Get all groups for the logged in user

Parameters (2):


http://developers.f8.facebook.com/documentation.php?v=1.0&method=groups.get

userId The Facebook userId to return groups for

Parameters (3):


groupListA collection of group ids. Return all groups matching a group id in the list.

Parameters (4):


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:







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):

http://developers.f8.facebook.com/documentation.php?v=1.0&method=groups.get


None Get all albums for the logged in user

Parameters (2):


userId Facebook userid to retrieve all albums for

Parameters (3):


albumList Collection of Facebook album ids to retrieve

Parameters (4):


userId Facebook userid to retrieve albums for

albumList Collection of Facebook album ids to retrieve

Return Type: Collection<Album>

Exceptions:







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)

http://developers.f8.facebook.com/documentation.php?v=1.0&method=photos.getAlbums

Definition (3): public Collection<Photo> GetPhotos(string albumId, Collection<string> photoList)

Parameters (1):


albumId The Facebook identifier of the album to retrieve photos for

Parameters (2):


photoList Collection of Facebook photo identifier to return information about

Parameters (3):


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:







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:

http://developers.f8.facebook.com/documentation.php?v=1.0&method=photos.getTags


photoList Collection of Facebook photo identifiers to return tags for

Return Type: Collection<PhotoTag>

Exceptions:







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):


none Get the user profile for the logged in user

Parameters(2):


userIds Comma separated list of Facebook user identifiers

Return Type: User

Exceptions:



http://developers.f8.facebook.com/documentation.php?v=1.0&method=users.getInfo





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:


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:







5.2 Facebook Data Objects

5.2.1 Album ClassThis class represents a Facebook photo album.

http://developers.f8.facebook.com/documentation.php?v=1.0&method=photos.upload

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


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


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.


5.2.3.10 Property: PictureUrlThe url of this event’s picture


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


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


5.2.4.5 Property: NetworkIdThe Facebook identifier of the network that the group is part of


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.


5.2.4.8 Property: PictureUrlThe url of this group’s picture


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


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.


5.2.6.18 Property: PictureUrlThe url of this user’s Facebook picture


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.


5.2.10.2 Property: NetworkIdThe Facebook unique identifier of the network.


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.


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;…


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;

…

http://api.facebook.com/

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;

…


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

Documents

Face Book Developer Toolkit