facebook developer toolkit

Facebook Developer Toolkit v1.2 Developed for Microsoft By Clarity Consulting Inc. ‐ www.claritycon.com

Table Of Contents 1 Leveraging the Facebook API in 5 minutes .......................................................................................... 4

1.1 Desktop Development .................................................................................................................. 4

1.2 Web Development ........................................................................................................................ 7

1.3 IFrame Canvas Development ...................................................................................................... 12

1.4 FBML Canvas Development ........................................................................................................ 13

1.5 AJAX in IFrame Canvas ................................................................................................................ 15

1.6 Silverlight in IFrame Canvas ........................................................................................................ 17

2 Pre‐requisites ..................................................................................................................................... 20

3 Introduction ........................................................................................................................................ 20

4 Overview ............................................................................................................................................. 21

4.1 Facebook API Overview .............................................................................................................. 21

4.2 Using the FacebookService to Access the API ............................................................................. 21

4.2.1 Infinite Sessions .................................................................................................................. 21

4.3 Facebook Desktop Development ................................................................................................ 22

4.4 Facebook Web Development ...................................................................................................... 22

4.5 Facebook Canvas Development .................................................................................................. 23

4.6 Using LINQ ................................................................................................................................... 24

5 Detailed Class Design ......................................................................................................................... 24

5.1 Facebook.Components ............................................................................................................... 24

5.1.1 FacebookService Class ........................................................................................................ 24

5.2 Facebook Data Objects ............................................................................................................... 47

5.2.1 Album Class ......................................................................................................................... 47

5.2.2 Photo Class .......................................................................................................................... 49

5.2.3 FacebookEvent Class ........................................................................................................... 51

5.2.4 Group Class ......................................................................................................................... 53

5.2.5 GroupUser Class .................................................................................................................. 56

5.2.6 User Class ............................................................................................................................ 56

5.2.7 SchoolHistory Class ............................................................................................................. 62

5.2.8 HighSchool Class ................................................................................................................. 62

5.2.9 HigherEducation Class ......................................................................................................... 63

5.2.10 Network Class ..................................................................................................................... 63

5.2.11 Location Class ...................................................................................................................... 64

5.2.12 Work Class ........................................................................................................................... 65

6 Code Snippets ..................................................................................................................................... 65

6.1 Windows Form: Application Setup ............................................................................................. 65

6.2 Windows Form: Retrieving Friends ............................................................................................. 66

6.3 Windows Form: Utilizing the FriendList Control ......................................................................... 66

6.4 Windows Form: Hooking a FriendList Control to a Profile Control ............................................. 67

6.5 Web Application: Authentication Process .................................................................................. 67

Release Notes: ............................................................................................................................................ 70

Version 1.1: ............................................................................................................................................. 70

Version 1.2: ............................................................................................................................................. 70

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 – Project o 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 Event o 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 Basic

Public Partial Class _Default Inherits Page

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 = "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 Basic 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")

• 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 user If (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 page ElseIf (Not String.IsNullOrEmpty(authToken)) Then _fbService.CreateSession(authToken) Session("Facebook_session_key") = _fbService.SessionKey Session("Facebook_userId") = _fbService.UserId Session("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 Basic Else 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 Basic If (Not IsPostBack) Then ' Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends() End If

1.3 IFrame Canvas Development One type of canvas page supported by the Facebook platform is the IFrame canvas. With this type of canvas page, facebook will host an iframe containing the content for you application. This type of canvas can not take advantage of the features of fbml, but allows for more traditional web development practices for facebook applications.

How to start your IFrame canvas application using the Facebook Developer Toolkit.

• Request a new developer api key from http://www.facebook.com/developers/ • Configure the following fields. The values here are the values used by the sample, you can

replace with your own values. o Callback URL: http://facebook.claritycon.com/IFrame/ o Canvas Page URL : aspnetcanvasiframe o Use IFRAME: true; Use FBML: false o Application Type: Website o Can your application be added on facebook: yes o Post‐Add URL: http://apps.facebook.com/aspnetcanvasiframe (same as canvas page) o Default Profile Box: Wide o Side Nav URL: http://apps.facebook.com/aspnetcanvasiframe (same as canvas page)

• Create new asp.net website in Visual Studio • Add reference to Facebook.dll • Add reference to Facebook.WebControls.dll • Update codebehind (Default.aspx.cs) on Default.aspx to subclass

Facebook.WebControls.CanvasIFrameBasePage Visual C#

using Facebook; using Facebook.WebControls;

public partial class _Default : CanvasIFrameBasePage {

Visual Basic

Imports Facebook Imports Facebook.WebControls

Public Partial Class _Default

Inherits CanvasIFrameBasePage

• Add code to set API key, secret (Make sure to use your own api key and secret acquired during above)

• Add code to call base.Page_Loaded Visual C#

private const string FACEBOOK_API_KEY = "YOURAPIKEYHERE"; private const string FACEBOOK_SECRET = "YOURSECRETHERE"; new protected void Page_Load(object sender, EventArgs e) { base.Api = FACEBOOK_API_KEY; base.Secret = FACEBOOK_SECRET; base.Page_Load(sender, e);

Visual Basic

Private Const FACEBOOK_API_KEY As String = "YOURAPIKEYHERE" Private Const FACEBOOK_SECRET As String = "YOURSECRETHERE"

Shadows Protected Sub Page_Load(ByVal sender As Object, ByVal e As

EventArgs) MyBase.Api = FACEBOOK_API_KEY MyBase.Secret = FACEBOOK_SECRET MyBase.Page_Load(sender, e)

• Add code to use FacebookService to invoke API calls on behalf of the logged in user.


{ // Use the FacebookService Component to populate Friends

Facebook.Entity.User u = this.FBService.GetUserInfo(); Collection<Facebook.Entity.User> f = this.FBService.GetFriends();

Visual Basic If (Not IsPostBack) Then

Dim u As Facebook.Entity.User = Me.FBService.GetUserInfo() Dim f As Collection(Of Facebook.Entity.User) = Me.FBService.GetFriends()

• Optionally, if you prefer to use Cookies instead of Sessions to pass Facebook Session information between pages, set the UseSession property of the CanvasIFrameBasePage to false

• Optionally, if you prefer to not automatically redirect users who have not already added your application to the add page (if you prefer to have an information page with a link to the add functionality), set the AutoAdd property of CanvasIFrameBasePage to false

• Publish Website to publicly available location • Access application using http://apps.facebook.com/YOURCANVASPAGE

1.4 FBML Canvas Development FBML (Facebook Markup Lanaguage) is a subset of HTML with some Facebook specific features. The second type of Facebook Canvas application that is supported is the FBML canvas. With an FBML

canvas, the developer is essentially developing an FBML web service that the Facebook server can invoke and the service will emit FBML that can be rendered as HTML by the displayed page. This canvas type allows for using some powerful facebook specific constructs that help to developers provide a better Facebook integrated experience.

How to start your FBML canvas application using the Facebook Developer Toolkit.

• Request a new developer api key from http://www.facebook.com/developers/ • Configure the following fields. The values here are the values used by the sample, you can

replace with your own values. o Callback URL: http://facebook.claritycon.com/FBML/ o Canvas Page URL : aspnetcanvasfbml o Use IFRAME: false; Use FBML: true o Application Type: Website o Can your application be added on facebook: yes o Post‐Add URL: http://apps.facebook.com/aspnetcanvasfbml (same as canvas page) o Default Profile Box: Wide o Side Nav URL: http://apps.facebook.com/aspnetcanvasfbml (same as canvas page)

• Create new asp.net website in Visual Studio • Add reference to Facebook.dll • Add reference to Facebook.WebControls.dll • Update Default.aspx to remove all of the default html in the page, to ensure no FBMl

compatibilities. • Update codebehind (Default.aspx.cs) on Default.aspx to subclass

Facebook.WebControls.CanvasIFrameBasePage Visual C#

using Facebook; using Facebook.WebControls;

public partial class _Default : CanvasFBMLBasePage {

Visual Basic

Imports Facebook Imports Facebook.WebControls

Public Partial Class _Default

Inherits CanvasFBMLBasePage

• Add code to set API key, secret (Make sure to use your own api key and secret acquired during above)

• Add code to call base.Page_Loaded Visual C#

private const string FACEBOOK_API_KEY = "YOURAPIKEYHERE"; private const string FACEBOOK_SECRET = "YOURSECRETHERE"; new protected void Page_Load(object sender, EventArgs e) {

base.Api = FACEBOOK_API_KEY; base.Secret = FACEBOOK_SECRET; base.Page_Load(sender, e);

Visual Basic

Private Const FACEBOOK_API_KEY As String = "YOURAPIKEYHERE" Private Const FACEBOOK_SECRET As String = "YOURSECRETHERE"

Shadows Protected Sub Page_Load(ByVal sender As Object, ByVal e As

EventArgs) MyBase.Api = FACEBOOK_API_KEY MyBase.Secret = FACEBOOK_SECRET MyBase.Page_Load(sender, e)

• Add code to use FacebookService to invoke API calls on behalf of the logged in user.


{ // Use the FacebookService Component to populate Friends

Facebook.Entity.User u = this.FBService.GetUserInfo(); Collection<Facebook.Entity.User> f = this.FBService.GetFriends();

Visual Basic If (Not IsPostBack) Then

Dim u As Facebook.Entity.User = Me.FBService.GetUserInfo() Dim f As Collection(Of Facebook.Entity.User) = Me.FBService.GetFriends()

• Optionally, if you prefer to not automatically redirect users who have not already added your application to the add page (if you prefer to have an information page with a link to the add functionality), set the AutoAdd property of CanvasIFrameBasePage to false

• Publish Website to publicly available location • Access application using http://apps.facebook.com/YOURCANVASPAGE

1.5 AJAX in IFrame Canvas

Using the ASP.NET AJAX extensions within for IFrame Canvas application is pretty straightforward. However, one important note, AJAX from an IFrame is not supported in without Framework 3.5 installed on the WebServer. This is a big obstacle for anyone using a public hosting service until Framework 3.5 GoLive licensing is available. The following walkthrough assumes that Framework 3.5 is installed. This walkthrough describes the web.config updates required to enable the asp.net ajax extensions on your existing asp.net web site. And I simple page illustrating the usage.

1. Install ASP.NET Ajax Extensions from http://ajax.asp.net/ 2. Install .NET Framework 3.5 from

http://www.microsoft.com/downloads/details.aspx?FamilyId=E3715E6F‐E123‐428B‐8A0F‐028AFB9E0322&displaylang=en

3. Open your web.config, in the system.web section add the following line:

<pages>

<controls> <add tagPrefix="asp" namespace="System.Web.UI" assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/> </controls> </pages>

This will save you having to have the following directive at the top of each page:

<%@ Register Assembly="System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" Namespace="System.Web.UI" TagPrefix="asp" %>

4. Verify that System.Web section has the following httpHandlers and httpModules configured, if not, add the missing settings:

<httpHandlers> <remove verb="*" path="*.asmx"/> <add verb="*" path="*.asmx" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/> <add verb="*" path="*_AppService.axd" validate="false" type="System.Web.Script.Services.ScriptHandlerFactory, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/> <add verb="GET,HEAD" path="ScriptResource.axd" type="System.Web.Handlers.ScriptResourceHandler, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" validate="false"/> </httpHandlers> <httpModules> <add name="ScriptModule" type="System.Web.Handlers.ScriptModule, System.Web.Extensions, Version=1.0.61025.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"/> </httpModules>

5. Add a new .aspx file (in our example, AJAXSample.aspx 6. Add a ScriptManager to the .aspx page

<asp:ScriptManager ID="ScriptManager1" runat="server" />

7. Add an UpdatePanel with ContentTemplate

<asp:UpdatePanel ID="upPanel" runat="server"> <ContentTemplate> <asp:Label id="lblUpdate" runat="server" Text="Before click" /> <asp:Button ID="btnAjax" runat="server" Text="Fire Ajax" OnClick="btnAjax_Click" /> </ContentTemplate> </asp:UpdatePanel>

8. That is it, now controls within your UpdatePanel will be updated and fire events without posting back the main Browser thread.

9. In our example, we catch the button press and update the label and button in code behind. The page is updated without posting back.

Visual C# protected void btnAjax_Click(object sender, EventArgs e) { lblUpdate.Text = "After click"; btnAjax.Text = "Fired Ajax"; btnAjax.Enabled = false; }

Visual Basic Protected Sub btnAjax_Click(ByVal sender As Object, ByVal e As EventArgs) lblUpdate.Text = "After click" btnAjax.Text = "Fired Ajax" btnAjax.Enabled = False End Sub

1.6 Silverlight in IFrame Canvas

Using Silverlight in a Canvas page is tricky. You can not directly reference the Facebook.dll from a Silverlight control. The following is a list of issues preventing direct using of the FacebookService from Silverlight.

1. Some namespaces used in the Facebook.dll (wrapper to the API) are not supported in Silverlight namespace. Most notably: System.XML, System.Web.

2. Silverlight 1.1 Alpha does not support cross domain posts. 3. It will be tough to manage the facebook login process from the Silverlight control, since we can

not show the facebook hosted login page.

With these limitations, the only technique available to use Silverlight is to do 2 things. First have the ASPX page that hosts the Silverlight content handle the authentication and pass the Facebook Session information to the Silverlight control, and then have the Silverlight control use a proxy webservice to access the FacebookService. Here is a step by step example of a simple example that retrieves an array of Facebook friends from Silverlight:

• Add a new webservice (SilverlightService.asmx) to the Canvas web site project. This webservice is a proxy used by the silverlight application to call Facebook

• Update the website project web.config to support the web service. • Add a ScriptService attribute to SilverlightService to enable it to support JSON calls • Add WebMethod GetFriends wrapping the FacebookService.GetFriends(), this method needs to

take the 4 parameters that comprise a facebook session, so that calls can maintain context. Visual C# [WebService(Namespace = "http://facebook.claritycon.com/")] [WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)] [System.Web.Script.Services.ScriptService] public class SilverlightService : System.Web.Services.WebService

{ Facebook.Components.FacebookService _fbService = new Facebook.Components.FacebookService();

[WebMethod] public UserJSON[] GetFriends(string api, string secret, string session, string userid)

{ Visual Basic <WebService(Namespace := "http://facebook.claritycon.com/"),

WebServiceBinding(ConformsTo := WsiProfiles.BasicProfile1_1), System.Web.Script.Services.ScriptService> _ Public Class SilverlightService

Inherits System.Web.Services.WebService Private _fbService As Facebook.Components.FacebookService =

New Facebook.Components.FacebookService() <WebMethod> _ Public Function GetFriends(ByVal api As String, ByVal secret As String,

ByVal session As String, ByVal userid As String) As UserJSON()

• Created a stripped down version of the Facebook.Entity.User class that is serializiable by JSON. JSON can't serialize enums or subclasses. So, for this I just stripped them out. This is called UserJSON and is currently just a member of my ASPNETPlatformSamples web site.

• In the GetFriends WebMethod, converted Collection of Users returned from Facebook call to Array of JSON compatible users.

Visual C# public UserJSON[] GetFriends(string api, string secret, string session, string userid) { _fbService.ApplicationKey = api; _fbService.Secret = secret; _fbService.SessionKey = session; _fbService.UserId = userid; Collection<Facebook.Entity.User> friends = _fbService.GetFriends();

UserJSON[] x = UserJSON.ConvertFacebookUserArray(friends); Visual Basic

Public Function GetFriends(ByVal api As String, ByVal secret As String, ByVal session As String, ByVal userid As String) As UserJSON() _fbService.ApplicationKey = api _fbService.Secret = secret _fbService.SessionKey = session _fbService.UserId = userid Dim friends As Collection(Of Facebook.Entity.User) = _fbService.GetFriends() Dim x As UserJSON() = UserJSON.ConvertFacebookUserArray(friends)

Return x

• Create a new Canvas page (IFrame\Silverlight.aspx), alongside to my other IFrame canvas pages • Add a placeholders in the .aspx for the Silverlight control and 4 hidden fields to store the

facebook context. Visual C#

<head> <title>Silverlight Project Test Page </title> <script type="text/javascript" src="Silverlight.js"></script> <script type="text/javascript" src="CreateSilverlight.js"></script> </head> <body> <form id="Form1" runat="server"> <asp:HiddenField ID="hidAPI" runat="server" /> <asp:HiddenField ID="hidSecret" runat="server" /> <asp:HiddenField ID="hidSession" runat="server" /> <asp:HiddenField ID="hidUser" runat="server" /> <div id="SilverlightControlHost" > <script type="text/javascript"> createSilverlight(); </script> </div>

</form> Visual Basic

<head> <title>Silverlight Project Test Page </title> <script type="text/javascript" src="Silverlight.js"></script> <script type="text/javascript" src="CreateSilverlight.js"></script> </head> <body> <form id="Form1" runat="server"> <asp:HiddenField ID="hidAPI" runat="server" /> <asp:HiddenField ID="hidSecret" runat="server" /> <asp:HiddenField ID="hidSession" runat="server" /> <asp:HiddenField ID="hidUser" runat="server" /> <div id="SilverlightControlHost" > <script type="text/javascript"> createSilverlight(); </script> </div>

</form> • Add code in code‐behind to populate hidden fields (so they can be accessed by silverlight

control). Visual C#

public partial class Silverlight : CanvasIFrameBasePage { private const string FACEBOOK_API_KEY = "c559128010f3edee33796fd4205361c2"; private const string FACEBOOK_SECRET = "85887d1c9a8334e5059742468a5400ee"; new protected void Page_Load(object sender, EventArgs e) { base.Api = FACEBOOK_API_KEY; base.Secret = FACEBOOK_SECRET; base.Page_Load(sender, e); hidAPI.Value = this.FBService.ApplicationKey;

hidSecret.Value = this.FBService.Secret; hidSession.Value = this.FBService.SessionKey;

hidUser.Value = this.FBService.UserId; Visual Basic

Partial Public Class Silverlight Inherits CanvasIFrameBasePage Private Const FACEBOOK_API_KEY As String = "c559128010f3edee33796fd4205361c2" Private Const FACEBOOK_SECRET As String = "85887d1c9a8334e5059742468a5400ee" Protected Shadows Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs) MyBase.Api = FACEBOOK_API_KEY MyBase.Secret = FACEBOOK_SECRET MyBase.Page_Load(sender, e) hidAPI.Value = Me.FBService.ApplicationKey hidSecret.Value = Me.FBService.Secret hidSession.Value = Me.FBService.SessionKey

hidUser.Value = Me.FBService.UserId • Create a new silverlight project using Orcas • Add a web reference to the above ASMX file (on your public domain) • Add code in page_loaded event handler of xaml code behind to call the GetFriends method on

the WebService to retrieve an array of friends. • Write text to a textblock with the count that was found. • Add a Silverlight Reference into the website project. This essentially copies the .xaml from

the Silverproject, and the compiled .xaml.cs into a ClientBin folder of the web site project so they can be accessed from within the website.

• You can see it in action, by going to my IFrame canvas sample. After logging in and adding the application, you should have a Silverlight demo link which will show the Silverlight page.

• The code from this walkthrough is in the ASPNETPlatformSamples web project and SilverlightWebServiceClient

2 Pre‐requisites First, 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 Introduction This 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 Overview All 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 Overview The 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 API The 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 Sessions The 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, Secret and SessionKey that are associated with the user and set them on the FacebookService whenever this user returns.

4.3 Facebook Desktop Development To 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.Generic Imports System.Collections.ObjectModel … Dim friends As Collection(Of User) = FacebookService1.GetFriends()

4.4 Facebook Web Development The 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 Pages b. Select Start Options c. 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 Facebook Canvas Development In addition to standalone web and desktop applications, Facebook also supports “Canvas” applications. Canvas applications are integrated directly into the website user experience on the facebook.com website. Canvas application have the ability to display information on a user’s profile, publish to user’s mini‐feeds and spread themselves organically through Facebook’s social network. For more information about building a Facebook Canvas application read Anatomy of a Facebook Application here, http://developers.facebook.com/anatomy.php.

Canvas application can be one of two types. FBML Canvas applications leverage Facebook Markup language to provide a consistent integrated user experience for Facebook users. FBML canvas applications essentially are constructed by the developer building a FBML “Web Service” that can be

called by the Facebook Server and return some FBML. The Facebook Server will then translate that FBML into HTML to display on Facebook hosted page. The second type of Canvas application is the IFrame Canvas application. In this type of canvas, the Facebook web page will simply show an IFrame to content hosted by the developer’s application. This type of canvas can not leverage FBML functionality, but does have the advantage of a much more typically web development experience.

The Facebook Developer Toolkit provides infrastructure for building both types of canvas applications. First, there is a CanvasFBMLBasePage and CanvasIFrameBasePage in the Facebook.WebControls assemblies. These base pages take care of all of the plumbing needed to successfully host a canvas application on the facebook site. In addition, the ASPNETPlatformSamples website shows samples of both types of Canvas pages and how to link to other canvas pages with one canvas application. See Sections 1.3 and 1.4 above for a detailed walkthrough

4.6 Using LINQ The 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 Class This 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: ApplicationKey This 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: IsDesktopApplication This 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: Secret This 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: SessionExpires This 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: SessionKey This 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: UserId This 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: AddTag This 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

yCoord The 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: AreFriends This 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):


userId1 The Facebook identifier of the first user

userId2 The Facebook identifier of the second user

Parameters (2):


user1 The 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: ConnectToFacebook This 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: CreateSession This 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: GetEventMembers This 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: GetEvents This 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):


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.

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.

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.

endDate Only retrieve events matching the above criteria and ending before this date.

Return Type: Collection<FacebookEvent>

Exceptions:







5.1.1.13 Method: GetFriends This 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:







5.1.1.14 Method: GetFriendsAppUsers This 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: GetFriendsNonAppUsers This method is not supported by the Facebook API. This method is used to get all the friends of the logged in user that are not users of this consuming application.

Definition: public Collection<User> GetFriendsNonAppUsers()

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.16 Method: GetGroupMembers This 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:


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.17 Method: GetGroups This 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):


userId The Facebook userId to return groups for

Parameters (3):


groupList A 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.18 Method: GetGroups This method wraps the Facebook API method notifications.get. This method is used to retrieve the notifications for the current user.

Definition: public Notifications GetNotifications()

Parameters:


None Get all notifications for the logged in user

Return Type: Notifications

Exceptions:







5.1.1.19 Method: GetPhotoAlbums This 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):


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.20 Method: GetPhotos This 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(User user)

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

Definition (5): public Collection<Photo> GetPhotos(string albumId, Collection<string> photoList, User user)

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


User The user of the album to retrieve photos for

Parameters (4):




Parameters (5):




User The user of the album to retrieve photos for

Return Type: Collection<Photo>

Exceptions:







5.1.1.21 Method: GetTags This 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:


photoList Collection of Facebook photo identifiers to return tags for

Return Type: Collection<PhotoTag>

Exceptions:







5.1.1.22 Method: GetUserInfo This 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)

Definition(3): public Collection<User> GetUserInfo(Collection<string> userIds)

Parameters(1):


None Get the user profile for the logged in user

Parameters(2):


userIds Comma separated list of Facebook user identifiers

Parameters(3):


userIds Collection of Facebook user identifiers

Return Type: User

Exceptions:







5.1.1.23 Method: UploadPhoto This 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.1.1.24 Method: SetFBML This method wraps the Facebook API method profile.setFBML. This method is used to add profile functionality using FBML.

Definition(1): public string SetFBML(string markup)

Definition(2): public string SetFBML(string markup, string userId)

Parameters(1):


markup FBML

Parameters(2):


markup FBML

userId The facebook identifier of the user’s profile to write to

Return Type: string – status

Exceptions:







5.1.1.25 Method: DirectFQLQuery This method wraps the Facebook API method fql.query. This method is used to execute any arbitrary FQL and return the XML result.

Definition: public string DirectFQLQuery(string query)

Parameters:


query Any FQL query

Return Type: xml string

Exceptions:







5.1.1.26 Method: SendNotification This method wraps the Facebook API method notification.send. This method is used to post a message to a user’s mini‐feed.

Definition(1): public string SendNotification(string markup, string toList)

Definition(2): public string SendNotification(string markup, string toList, string email)

Parameters(1):


markup FBML for the notification

toList Comma separated list of recipient user ids

Parameters(2):




email FBML for email body


Exceptions:







5.1.1.27 Method: SendRequest This method wraps the Facebook API method notifications.sendRequest. This method is used to send an invite to an event or group

Definition: public string SendRequest(string markup, string toList, string requestType, Uri imageUrl, bool isInvite)

Parameters:




requestType Group or Event

imageUrl Url of image to display in the request

isInvite Whether the request is an invitation or not


Exceptions:







5.1.1.28 Method: PublishAction This method wraps the Facebook API method feed.publishActionOfUser. This method is publish the action of a user

Definition: public string PublishAction(string title, string body, Collection<PublishImage> images)

Definition(2): public string PublishAction(string title, string body, Collection<PublishImage> images, int priority)

Parameters:


title The album identifier to upload the photo to. If null, then will upload to default album

body File containing the photo to upload.

images The url and link of up to 4 images

Parameters(2):





priority 1 – 100


Exceptions:







5.1.1.29 Method: PublishStory This method wraps the Facebook API method feed.publishStoryToUser. This method is publish a story to a specific user

Definition(1): public string PublishStory(string title, string body, Collection<PublishImage> images)

Definition(2): public string PublishStory(string title, string body, Collection<PublishImage> images, int priority)

Parameters(1):





Parameters(2):





priority 1 – 100


Exceptions:







5.1.1.30 Method: GetLoggedInUser This method wraps the Facebook API method users.GetLoggedInUSer. This method is used to get the facebook user id of the currently logged in user.

Definition: public string GetLoggedInUser()

Parameters:


N/A

Return Type: N/A

Exceptions:







5.2 Facebook Data Objects

5.2.1 Album Class This class represents a Facebook photo album.

5.2.1.1 Property: AlbumId The Facebook identifier of the album

Definition: public string AlbumId

5.2.1.2 Property: CoverPhotoId The Facebook identifier of photo that is used as the cover photo for the album

Definition: public string CoverPhotoId

5.2.1.3 Property: CreateDate The date that the album was created

Definition: public DateTime CreateDate

5.2.1.4 Property: Description The user entered description of the album

Definition: public string Description

5.2.1.5 Property: Location The location that the album pertains to

Definition: public string Location

5.2.1.6 Property: ModifiedDate The date that this album was last updated

Definition: public DateTime ModifiedDate

5.2.1.7 Property: Name The name of the album

Definition: public string Name

5.2.1.8 Property: OwnerUserId The Facebook user id of the person who created the album

Definition: public string OwnerUserId

5.2.2 Photo Class This class contains the information about a Facebook Photo.

5.2.2.1 Property: AlbumId A Facebook unique identifier of the album that the photo is part of.

Definition: public string AlbumId

5.2.2.2 Property: Caption The caption of the photo.

Definition: public string Caption

5.2.2.3 Property: CreateDate A date when the photo was first uploaded.

Definition: public DateTime CreateDate

5.2.2.4 Property: Link The photo link.

Definition: public Uri Link

5.2.2.5 Property: OwnerUserId A Facebook unique identifier of user who owns the photo.

Definition: public string OwnerUserId

5.2.2.6 Property: PhotoId A Facebook unique identifier of the photo.

Definition: public string PhotoId

5.2.2.7 Property: Picture The 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: PictureUrl The url of this picture

Definition: public Uri PictureUrl

5.2.2.9 Property: PictureSmall The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. (small version)

Definition: public Image PictureSmall

5.2.2.10 Property: PictureSmallUrl The url of this picture (small version)

Definition: public Uri PictureSmallUrl

5.2.2.11 Property: PictureBig The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. (big version)

Definition: public Image PictureBig

5.2.2.12 Property: PictureBigUrl The url of this picture

Definition: public Uri PictureBigUrl

5.2.3 FacebookEvent Class This class represents a Facebook event.

5.2.3.1 Property: Creator The Facebook identifier of the user who created the event

Definition: public string Creator

5.2.3.2 Property: Description Description of the event


5.2.3.3 Property: EndDate The date that the events ends

Definition: public DateTime EndDate

5.2.3.4 Property: EventId The Facebook identifier of the event.

Definition: public string EventId

5.2.3.5 Property: Host The Facebook user id of the host of the event

Definition: public string Host

5.2.3.6 Property: Location The name of the place where the event will take place.

Definition: public string Location

5.2.3.7 Property: Name The name of the event


5.2.3.8 Property: NetworkId The Facebook identifier of the network that this event is a part of

Definition: public string NetworkId

5.2.3.9 Property: Picture The 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: PictureUrl The url of this event’s picture


5.2.3.11 Property: StartDate The date and time when the event starts

Definition: public DateTime StartDate

5.2.3.12 Property: SubType The seconary group of event type.

Definition: public string SubType

5.2.3.13 Property: TagLine The tagline of the event if one was specified

Definition: public string TagLine

5.2.3.14 Property: Type The primary grouping of the event

Definition: public string Type

5.2.3.15 Property: UpdateDate The Facebook user id of the person who created the album

Definition: public DateTime UpdateDate

5.2.4 Group Class This class contains represents a Facebook group.

5.2.4.1 Property: Creator The Facebook identifier of the user who created the group

Definition: public string Creator

5.2.4.2 Property: Description The description of the group


5.2.4.3 Property: GroupId The Facebook identifier of the group

Definition: public string GroupId

5.2.4.4 Property: Name The user entered name of the group


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


5.2.4.6 Property: Office The address of the group’s office if it has one.

Definition: public string Office

5.2.4.7 Property: Picture The 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: PictureUrl The url of this group’s picture


5.2.4.9 Property: RecentNews Free form text describing recent news associated with the group

Definition: public string Recent News

5.2.4.10 Property: SubType The seconary group of group type.

Definition: public string SubType

5.2.4.11 Property: Type The primary grouping of the event

Definition: public string Type

5.2.4.12 Property: UpdateDate The last date and time that changes were made to the group

Definition: public DateTime UpdateDate

5.2.4.13 Property: Venue The name of the venue where the group meetings occur

Definition: public string Venue

5.2.4.14 Property: WebSite The url of the website for the group.

Definition: public string WebSite

5.2.5 GroupUser Class This class contains represents a Facebook group.

5.2.5.1 Property: GroupId The Facebook identifier of the group

Definition: public string GroupId

5.2.5.2 Property: Positions Collection of positions held by this user

Definition: public Collection<GroupPosition> Positions

5.2.5.3 Property: User The user object representing the profile of the user

Definition: public User User

5.2.5.4 Property: UserId The Facebook identified of the user

Definition: public string UserId

5.2.6 User Class This class contains represents a Facebook user.

5.2.6.1 Property: AboutMe A string describing the user. Free form.

Definition: public string AboutMe

5.2.6.2 Property: Activities Free form text describing the activities this user is interested in.

Definition: public string Activities

5.2.6.3 Property: Affiliations A collection of Networks this user belongs to

Definition: public Collection<Network> Affiliations

5.2.6.4 Property: Birthday The day this user was born

Definition: public DateTime? Birthday

5.2.6.5 Property: Books Free form text describing this user’s favorite books

Definition: public string Books

5.2.6.6 Property: CurrentLocation The current location for the user

Definition: public Location CurrentLocation

5.2.6.7 Property: FirstName The user’s first name

Definition: public string FirstName

5.2.6.8 Property: HometownLocation The location of the user’s hometown

Definition: public Location HometownLocation

5.2.6.9 Property: InterestedInGenders A collection containing enum values representing the genders that this person is interested in.

Definition: public Collection<Gender> InterestedInGenders

5.2.6.10 Property: Interests Free form text describing the user’s interests

Definition: public string Interests

5.2.6.11 Property: InterestedInRelationshipTypes A 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: LastName The user’s last name

Definition: public string LastName

5.2.6.13 Property: Movies Free form text describing the user’s favorite movies

Definition: public string Movies

5.2.6.14 Property: Music Free form text describing the user’s favorite music

Definition: public string Music

5.2.6.15 Property: Name The user’s name


5.2.6.16 Property: NotesCount The number of notes this user has associated with their Facebook account.

Definition: public int NotesCount

5.2.6.17 Property: Picture The 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: PictureUrl The url of this user’s Facebook picture


5.2.6.19 Property: PictureSmall The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. (small version)

Definition: public Image PictureSmall

5.2.6.20 Property: PictureSmallUrl The url of this picture (small version)

Definition: public Uri PictureSmallUrl

5.2.6.21 Property: PictureBig The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. (big version)


5.2.6.22 Property: PictureBigUrl The url of this picture

Definition: public Uri PictureBigUrl

5.2.6.23 Property: PictureSquare The actual image. Accessing this property will download the bytes of the image and serialize into an image. This does require a small performance hit. (big version)


5.2.6.24 Property: PictureSquareUrl The url of this picture

Definition: public Uri PictureSquareUrl

5.2.6.25 Property: PoliticalView An enum value representing the user’s political view

Definition: public PoliticalView PoliticalView

5.2.6.26 Property: Quotes Free form text representing the user’s favorite quotes

Definition: public string Quotes

5.2.6.27 Property: RelationshipStatus An enum value representing the user’s current relationship status.

Definition: public RelationshipStatus RelationshipStatus

5.2.6.28 Property: Religion Free form text representing the Religion

Definition: public string Religion

5.2.6.29 Property: SchoolHistory A data object representing the user’s education history

Definition: public SchoolHistory SchoolHistory

5.2.6.30 Property: Sex The user’s gender

Definition: public Gender Sex

5.2.6.31 Property: SignificantOtherId The Facebook user id of this user’s significant other

Definition: public string SignificantOtherId

5.2.6.32 Property: TVShows Free form text describing this user’s favorite TVShows

Definition: public string TVShows

5.2.6.33 Property: UserId The Facebook unique identifier of the user

Definition: public string UserId

5.2.6.34 Property: WallCount The number of messages that have been written on this user’s wall.

Definition: public int WallCount

5.2.6.35 Property: RelationshipStatus The Facebook identified of the user

Definition: public RelationshipStatus RelationshipStatus

5.2.6.36 Property: Status Data object representing the user’s current status. This object has message and time properties

Definition: public Status Status

5.2.6.37 Property: ProfileUpdateDate The date and time of the last time this user changed their profile.

Definition: public DateTime ProfileUpdateDate

5.2.6.38 Property: WorkHistory Collection of Work object representing this user’s employment history

Definition: public Collection<Work> WorkHistory

5.2.7 SchoolHistory Class This class contains Facebook user’s education history (including high school and college).

5.2.7.1 Property: HigherEducaton A collection of HigherEducation object representing the colleges this user attended.

Definition: public Collection<HigherEducation> HigherEducation

5.2.7.2 Property: HighSchool A HighSchool data object containing information about the high schools this user attended.

Definition: public HighSchool HighSchool

5.2.8 HighSchool Class This classs contains information about the high schools this user attended.

5.2.8.1 Property: GraduationYear The year this user graduated from college

Definition: public int GraduationYear

5.2.8.2 Property: HighSchoolOneId The Facebook unique identifier of the high school

Definition: public string HighSchoolOneId

5.2.8.3 Property: HighSchoolOneName The name of the high school

Definition: public string HighSchoolOneName

5.2.8.4 Property: HighSchoolTwoId The Facebook unique identifier of the high school

Definition: public string HighSchoolTwoId

5.2.8.5 Property: HighSchoolTwoName The name of the high school

Definition: public string HighSchoolTwoName

5.2.9 HigherEducation Class This class contains Facebook user’s college education history.

5.2.9.1 Property: AttendedFor An enum value representing if the school was attended for under graduate work or graduate work

Definition: public SchoolType AttendedFor

5.2.9.2 Property: ClassYear Graduation year

Definition: public int ClassYear

5.2.9.3 Property: Concentration A collection describing user’s majors

Definition: public Collection<string> Concentration

5.2.9.4 Property: School The name of the school

Definition: public string School

5.2.10 Network Class This class contains the information about a Facebook Network.

5.2.10.1 Property: Name The name of the network.


5.2.10.2 Property: NetworkId The Facebook unique identifier of the network.


5.2.10.3 Property: Status The status of the network (Open or Closed).

Definition: public string Status

5.2.10.4 Property: Type An enum value representing the type of the network (College, High School, Work or Region)

Definition: public NetworkType Type

5.2.10.5 Property: Year The year associated with the network.

Definition: public int Year

5.2.11 Location Class This class contains information about a geographic location.

5.2.11.1 Property: City A city of the location.

Definition: public string City

5.2.11.2 Property: Country A country of the location.

Definition: public Country Country

5.2.11.3 Property: State A state of the location.

Definition: public State State

5.2.11.4 Property: StateAbbreviation A postal abbreviation of the state of the location.

Definition: public StateAbbreviation StateAbbreviation

5.2.11.5 Property: ZipCode A zip code of the location.

Definition: public string ZipCode

5.2.12 Work Class This class contains Facebook user’s work history.

5.2.12.1 Property: CompanyName The name of the company.

Definition: public string CompanyName

5.2.12.2 Property: Description The description of job.


5.2.12.3 Property: EndDate The date that the user ended this employment.

Definition: public DateTime EndDate

5.2.12.4 Property: Location The location of the job.

Definition: public Location Location

5.2.12.5 Property: Position The user’s position/title.

Definition: public string Position

5.2.12.6 Property: StartDate The date the user started the job.

Definition: public DateTime StartDate

6 Code Snippets

6.1 Windows Form: Application Setup After 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 Friends The 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.Generic Imports System.Collections.ObjectModel …

Dim friends As Collection(Of User) = FacebookService1.GetFriends()

6.3 Windows Form: Utilizing the FriendList Control There 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.Generic Imports System.Collections.ObjectModel Imports Facebook.Controls …

friendList1.Friends = FacebookService1.GetFriends()

6.4 Windows Form: Hooking a FriendList Control to a Profile Control The 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.User End Sub

6.5 Web Application: Authentication Process Web 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 user If (Not String.IsNullOrEmpty(sessionKey)) Then _fbService.SessionKey = sessionKey _fbService.UserId = userId ' This will be executed when Facebook login redirects to our page ElseIf (Not String.IsNullOrEmpty(authToken)) Then _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") End If If (Not IsPostBack) Then ' Use the FacebookService Component to populate Friends MyFriendList.Friends = _fbService.GetFriends() End If

Release Notes:

Version 1.1: • Added methods to FacebookService to wrap the Notifications.get Facebook API call. Added a

new data object "Notifications" for wrapping the results.

• Added Status and ProfileUpdateDate to the User object. Status contains the user's Facebook Status Message and time when it was updated. ProfileUpdateDate contains the date when the user last updated their Facebook profile.

• Added SetFMBL method. Also correct GetRequestURL to correctly encode the format.

• Added DirectFQLQuery. As designed on f8 wiki.

• Fixed GetFriendsAppUsers. As designed on F8 wiki.

• Fixed to add error handling to Country parsing in LocationParser

• Added implementations of 2 notifications and 2 feeds apis.

• Fixed parameter sorting for feeds apis to work correctly.

• Change REST Call from GET to POST.

• Add GetLoggedInUser

• Fix handling for no returned secret

• Add overload to GetUserInfo that takes a Collection of user ids

Version 1.2: • Refactored FacebookService

• Added AsyncFacebookService

• Refactored Parsers and Entities into their own directory and namespace

• Added improved photo api

• Added Canvas Base pages to Facebook.WebControls

• Added Canvas samples to Facebook.WebControls

• Added IFrame Ajax sample

• Added IFrame Silverlight Example

• Updated to new notifications API **INTERFACE CHANGE**

• Updated PublishStory and PublishAction interfaces **INTERFACE CHANGE**

• Updated CreateAlbum interface to return created Album **INTERFACE CHANGE**

• Added SetFBML override taking in userid

• Added small and big picture url and bitmap to photo and user

• Added GetFriendsNonAppUsers method

facebook developer toolkit

Documents