The App Walkabout: Building Your First Facebook Application

The App Walkabout: Building Your First Facebook Application 


First Facebook Application 

In This Chapter Registering your app with Facebook Writing your first code for the Facebook API Setting default FBML for the Profile box Adding an icon and About page Let’s do this! The explorers of old would get a “lay of the lands” before venturing off into the unknown wilderness. In studying the geography, they would grasp the steepness of the mountains, the width of the valleys and plains, and the nature of the rivers or swamps. However, at some point, the explorers would eventually put down their maps and survey instruments and lead their teams into the wild. Now that you have had a chance to get a solid grasp of the Facebook Platform and its Social Graph, you are probably feeling antsy like those explorers and are ready to just do this. That’s what this chapter is all about. I walk you through each step of building your first application for the Facebook Platform. I keep the sample straightforward at this early stage, but you’ll be able to see each of the basic tasks you will want to perform, regardless of the complexity of your application. In this walkthrough, I show you how to build a basic PHP-based app. However, if you are using Java or another programming language, you can also follow along, substituting the PHP-specific commands as needed. 06_277959-ch02.qxp 5/5/08 11:25 AM Page 29 Registering an Application with Facebook Before coding the application itself, you are going to need to get some application-specific information from Facebook to communicate with the Facebook Platform. Your first step is, therefore, to register the application with Facebook. When you do so, you’ll get an API key and secret key that you can plug into your code. The following steps guide you through this registration process: 1. Go to www.facebook.com/developers. If you are not logged in to Facebook, you will be prompted to log in first. Figure 2-1 shows you the main Facebook developer’s page. Set Up New Application button Figure 2-1: Facebook. com/ developers is the place to start for setting up a new application. 30 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 30 2. Click the Set Up New Application button. The New Application page is displayed, as shown in Figure 2-2. 3. Enter the name of your application in the space provided. Choose it carefully because it will be the one displayed everywhere within Facebook. I am naming my test application Dummies Facebook Platform Tester. 4. Select the check box to confirm that you have read and accepted the terms of the Facebook Platform. Be sure that you fully read the terms before checking the box. Pay special attention to the permissible usage of the terms Facebook and Face. 5. Click the Optional Fields link to display several more settings, as shown in Figure 2-3. Figure 2-3: Additional application options. Figure 2-2: Creating a new Facebook application. Chapter 2: The App Walkabout: Building Your First Facebook Application 31 06_277959-ch02.qxp 5/5/08 11:25 AM Page 31 6. Add an e-mail address that you want to use for technical support issues. Facebook adds your account e-mail address by default, but you can change it as needed. 7. In the Callback URL field, enter the base URL for your application. The callback URL points to the application on your server. Be sure to point to a folder, not a specific page name (index.php). 8. In the Canvas Page URL field, enter the subfolder name that you would like to request for your Facebook application. All Facebook apps are under the apps.facebook.com domain, and then each has a unique subfolder name. Pick a folder name that’s identical or similar to your application name. You can use letters, underscores, or dashes, but numbers are not permitted. I highly recommend using all lowercase letters to avoid potential case sensitivity issues. When you enter the desired name, Facebook provides immediate feedback on whether it is available. For my example, I chose dummies because it was available. (Who else would be “dumb” enough to choose that URL?) If no validation seems to have occurred, try clicking into the text box again and tabbing to the next box. Occasionally, the validation routine needs to reset itself. 9. Select the Use FBML option button. You can display your application inside Facebook using FBML (Facebook Markup Language) or an iframe. When you select FBML, your pages are rendered by Facebook servers. When you select iframe, the content is rendered by your host server and displayed in an iframe on a Facebook page. Later I show you how to work with iframes, but for now, select FBML. 10. Select the Website option button. Facebook allows you to



define your application as a Web site or Desktop. A Web site app is a traditional Web app that integrates with Facebook. A Desktop app is a desktop-based app that accesses Facebook using the API. Use Web site for this example. 11. Do not select the Mobile Integration check box for now. See Chapter 12 for more on creating mobile Facebook apps. 32 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 32 12. Leave the IP Addresses of Servers Making Requests text box blank. You can use this option to specify the IP address(es) of your Web server(s). This option is useful if your secret key is stolen, as it would prevent other apps from impersonating your own if they do not originate from your servers. I recommend ignoring this option at this initial stage but considering it before your real-life application goes live to the world. 13. Select the Yes option button for Can Your Application Be Added on Facebook? This option is required to add your application to your own account. Don’t worry; you can limit other people’s access to your application in a moment. When you select Yes, more installation options are displayed at the end of the page. 14. If you have a terms of service document, specify its URL in the TOS URL field. Facebook requires users to accept the terms before they can install their terms of service documents. 15. In the Developers field, enter the name of any additional person who developed the Facebook application. Facebook does a lookup on the name you are typing and searches for a name match in the Facebook database. If others need to modify or have access to the application in Developer Mode, you can enter their names now. Or, if you prefer, you can always add them later. Figure 2-4 shows the completed form. You are now ready to continue with the Installation Options section. 16. Select the Users check box for Who Can Add Your Application to Their Facebook Account? 17. Select the All Pages option button. Facebook pages are specific business- or organization-oriented pages that can also have apps added to them. By choosing All Pages, you open up a wider audience to your application. 18. In the Post-Add URL text box, enter the URL that users are redirected to after installing the application. This URL is the canvas page URL (the Facebook URL you picked back in Step 8). It should not point to the callback URL on your server. Chapter 2: The App Walkabout: Building Your First Facebook Application 33 06_277959-ch02.qxp 5/5/08 11:25 AM Page 33 19. Enter a short description of your application in the Application Description text box. Be sure to clearly and succinctly describe what your application does for Facebook users. Never force a user to install your application to see what it does. 20. If you want to specify a URL that you want to redirect users to when they uninstall your application from their Facebook profile, enter one in the Post-Remove URL field. I am going to leave this box blank for this basic example. 21. In the Default FBML field, you can specify some default FBML or plain text that will appear in the canvas on the user’s profile page. For now, keep it simple. I show you how to do this programmatically later using the setFBML API call. 22. In the Default Action FBML field, you can specify default FBML to appear as an action item under the user’s profile picture. 23. For the Default Profile Box Column, select the Wide option button to specify the default column of a user’s profile. 24. Select the Developer Mode check box to prevent anyone else but you from installing the application. Until your application is ready to roll, be sure that this option is enabled (see Figure 2-5). You have one final section to fill in before you submit the application. Figure 2-4: Completing the basic application form. 34 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 34 25. In the Side Nav URL field, enter the canvas page URL of your application. This option is used when you want to add a link to your application from the left-side navigation menu. It should be a Facebook apps URL (http://apps.facebook.com/yourapp), not your callback URL. 26. If you have a privacy configuration page, add its URL in the Privacy URL field. I recommend leaving this option blank for this initial walk-through. 27. Specify Help documentation in the Help URL field. Again, at this early point, just skip this option. 28. Select the Private Installation check box. By enabling this option, you prevent adding stories to your News Feed and Mini-Feed concerning the application. Until you are ready to go live, you should probably select this box to keep your testing quiet. 29. Leave the Attachments fields blank. Applications can create “attachments” that are displayed in a drop-down menu on the message composer. When the user selects the attachment, the content you provide from the attachment callback URL is retrieved and placed inside an attachment box below the text in the message composer. For this initial application, I ignore this functionality. However, turn to Chapter 13 for details on how to work with attachments. The final options are displayed in Figure 2-6. Figure 2-5: Configuring the installation options. Chapter 2: The App Walkabout: Building Your First Facebook Application 35 06_277959-ch02.qxp 5/5/08 11:25 AM Page 35 30. Click the Submit button. When you click the Submit button, you are taken to the My Applications page (see Figure 2-7). Your application is added to Facebook, and an API key is created for it. If you encounter an error, it may appear as if you have to enter everything over again. However, check your My Applications page to see if the app was added in spite of the error. If so, simply click the Edit Settings link and correct the mistake. Figure 2-7: My Applications page. Figure 2-6: Specifying how to integrate with Facebook. 36 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 36 The My Applications page displays meta information for all your registered applications. Notice, in particular, the API key and secret key. You’ll need these two pieces of information to call Facebook from within your application. Creating a Simple Facebook Application When you have an API key and secret key, you are ready to create an application that can communicate with the Facebook Platform. Here’s how to do it using PHP: 1. Download the client library files of your programming language from the My Applications page (facebook.com/developers/apps.php). The client library files are your link to Facebook. As I mention in Chapter 1, Facebook officially supports PHP and Java client libraries, though you can find unofficial libraries for several additional languages at the Facebook Developers Wiki (wiki.developers.facebook.com). 2. Uncompress the downloaded file and copy the client library files via FTP to your Web server. Place these files in the folder you specified as the callback URL for your application. If you have problems uncompressing the .tar.gz file, you may wish to check out a compression utility like 7-Zip. The PHP client library is contained inside a main folder named facebook-platform. Inside this folder are these three subfolders: • client contains the PHP5 client library files: facebook.php, facebook_desktop.php, and facebookapi_php5_restlib. php. • footprints is a sample PHP5 application. • php4client provides a PHP4 version of the client library. For this example, you only need to use the facebook.php and face bookapi_php5_restlib.php files. However, I recommend copying all the files to your server using the existing folder structure so that you can be sure to have all files on hand as needed. In this walk-through, I assume that you’ll use this structure. 3. In your text editor, create a new file and save it as appinclude.php. You’ll add the Facebook initialization code in this file to connect to the Facebook Platform. This file should be included at the top of every PHP file used in your application. Chapter 2: The App Walkabout: Building Your First Facebook Application 37 06_277959-ch02.qxp 5/5/08 11:25 AM Page 37 4. Enter the following code into the appinclude.php file, inserting your API key, secret key, and callback URL in the appropriate places. Better yet, to save typing, you can also retrieve the code from this book’s companion Web site. require_login(); // Exception handler for invalid session_keys try { // If app is not added, then attempt to add if (!$facebook->api_client->users_isAppAdded()) { $facebook->redirect($facebook->get_add_url()); } } catch (Exception $ex) { // Clear out cookies for app and redirect user to a login prompt $facebook->set_user(null, null); $facebook->redirect($appcallbackurl); } ?> 5. On your Web server, create a new folder for your application. This folder will be used for appinclude.php and additional application files. The facebook.php path in the require_once statement of app include.php assumes that your app files are located in a separate, parallel folder structure than the Facebook client library files, such as \your_test_app \facebook-platform Be sure to update the path for facebook.php if your folder structure differs. 6. FTP appinclude.php to the application folder on your Web server. 7. In your text editor, create a new file and save it as index.php. 8. Add an h1 title, PHP start and end tags, and a require_once statement to your appinclude.php file, as follows: 38 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 38

Dummies Sample Application

9. After the require_once statement, enter the following two lines of PHP code to display the user’s ID and name: echo “
Your User ID is: $user
”; echo “
Your name is:
”; The $user variable is set inside the appinclude.php file to be the ID number of the current Facebook user. This value is printed in the first statement. The fb:name tag in the second statement is an FBML tag that renders the name of the specified user ID. The $user variable is used as the value of the uid attribute. The useyou attribute is set to false to prevent Facebook from substituting “you” with the username when the uid value is identical to the logged-on user ID. 10. Add a bulleted list of Facebook friends by entering the following code: echo “
You have several friends:
”; $friends = $facebook->api_client->friends_get(); echo “
    ”; foreach ($friends as $friend) { echo “
  • ”; } echo “
”; In this code, recall that the $facebook object was initiated in the appinclude.php file. With $facebook ready to go, the $facebook-> api_client object is then used for all Facebook API calls. In this case, the friends_get() method is called to return a list of user IDs of the user’s friends. Using a foreach construct, each of the friends is displayed as a list item. The fb:name tag is used to display the user’s name instead of the ID. Chapter 2: The App Walkabout: Building Your First Facebook Application 39 Avoiding dependencies If you prefer, you can also use the following procedure to include the facebook.php file but avoid potential issues with relative paths: require_once($_SERVER[“DOCUMENT_ROOT”] . ‘/facebookplatform/client/facebook.php”); 06_277959-ch02.qxp 5/5/08 11:25 AM Page 39 11. Save the file and copy it to the application folder via FTP on your Web server. You are now ready to display your app inside Facebook. 12. Enter the canvas page URL for your application in your browser. In my case, I access http://apps.facebook.com/dummies. If you browse to the canvas page URL from outside of Facebook, you will be presented with a Logon screen, with two checkboxes (Allow access to my info and Keep me logged in check boxes). Check these boxes to allow for tighter application integration. If you have never added the app to your Facebook account, then you will be asked whether or not to add it. The Facebook Platform redirects the request to your callback URL and then renders the results back inside the Facebook canvas, as shown in Figure 2-8. Listing 2-1 lists the full source code for the sample application. Listing 2-1: index.php

Dummies Sample Application

Your User ID is: $user

”; echo “
Your name is:
”; echo “
You have several friends:
”; $friends = $facebook->api_client->friends_get(); echo “
    ”; Figure 2-8: Displaying the sample application. 40 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 40 foreach ($friends as $friend) { echo “
  • ”; } echo “
”; ?> Note that if you access the callback URL folder from your browser, the page rendered would not contain the usernames, because non-Facebook application servers do not support FBML. Adding an Icon to the Application During the initial submittal process, Facebook does not provide the option of customizing the icon for the application. The icon is displayed alongside the application name in the left-side menu. Here’s how to add an image: 1. Point your Web browser to www.facebook.com/developers. 2. Click the See My Apps link in the My Applications box. 3. In the My Applications list, click the Edit Settings link for your application. 4. In the Base Options section, click the Change Your Icon link (see Figure 2-9). The Upload an Icon page is displayed, as shown in Figure 2-10. Figure 2-10: Most any square image can do the trick. The Icon section Figure 2-9: Adding an icon to your application. Chapter 2: The App Walkabout: Building Your First Facebook Application 41 06_277959-ch02.qxp 5/5/08 11:25 AM Page 41 5. Click the Choose File button and locate an image on your hard drive that graphically represents your application. You can use any normal Web graphic — JPG, PNG, or GIF. Facebook can convert your image into a 16x16 GIF image. 6. Select the certification check box to ensure that your image is appropriate for usage on Facebook. 7. Click the Upload Image button. After the file is uploaded and converted, you are taken back to the Edit Settings page. 8. Click the Save button. The icon is now displayed on the left-side menu (see Figure 2-11). Setting the Initial Content of the Application’s Profile Box When your application appears as a box on the Profile page, you can set its initial content in two ways: Using an interactive form: If you recall, back in Step 21 of the section “Registering an Application with Facebook,” earlier in this chapter, you can supply default FBML during the interactive registration process. By code: You can also use the profile_setFBML() method to set the display inside your code. To add default FBML to your application using profile_setFBML(), add the following code to your index.php file just after the require_once ‘appinclude.php’ statement: Dummies icon Figure 2-11: Icon is displayed beside the application name. 42 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 42 $default_text = “
Hey, ! This Dummies Sample Application provides all of the information you will ever need.
”; $facebook->api_client->profile_setFBML($default_text); When the application is accessed again, the supplied FBML is displayed in its box on the Profile page (see Figure 2-12). Adding an About Page Before you are done, you will want to add an About page for the application that describes the application to Facebook users. For a sample application like you have been building in this chapter, this step is optional. However, when you are developing the real thing, its About page is an important step in successfully marketing it to the Facebook community. Figure 2-12: You can supply default FBML for the Profile box. Chapter 2: The App Walkabout: Building Your First Facebook Application 43 06_277959-ch02.qxp 5/5/08 11:25 AM Page 43 Follow these instructions to create an About page: 1. Point your Web browser to www.facebook.com/developers. 2. Click the See My Apps link in the My Applications box. The My Applications page is displayed. 3. Click the Edit About Page link in your application box. 4. Click the Edit link beside the Application Information box. The Edit About Page page is displayed, as shown in Figure 2-13. Figure 2-13: Edit the About page. 44 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 44 5. If needed, modify the name of your application in the Application Name box. 6. Enter a description of your application in the Description of Application text box. Fully explain what your application does here. 7. Select the category(ies) that your application fits into. For a sample application, you can skip this option. But for real applications, be sure to be descriptive. 8. Specify developer information in the fields at the bottom of the page. 9. Click the Submit button. You will be taken to a page to add a picture (see Figure 2-14). Note that this is a larger image (such as 200 or 300 pixels in width), not the icon image that is used on the left-side menu. 10. Click the Choose File button and locate the desired Web graphic on your hard drive. 11. Select the terms of use check box to ensure that the image is appropriate for Facebook usage. 12. Click the Upload Picture button. You are returned to the My Applications page. 13. Click the View About Page link to see the page that you created. (See Figure 2-15.) Figure 2-14: Adding an image for your application. Chapter 2: The App Walkabout: Building Your First Facebook Application 45 06_277959-ch02.qxp 5/5/08 11:25 AM Page 45 Figure 2-15: Viewing the description of your application. 46 Part I: Getting Friendly with the Facebook Platform 06_277959-ch02.qxp 5/5/08 11:25 AM Page 46 Part II Poking the API 07_277959-pp02.qxp 5/5/08 11:25 AM Page 47 In this part . . . If you spend much time around Facebook, you may find yourself “poking” someone else. The exact interpretation of a “poke” is open to debate. To some, poking is a form of flirting. To others, a poke is merely the digital equivalent of a friendly, “Howdy.” In this part, you begin poking the Facebook Platform. You get a chance to flirt with the Facebook API and get to know it far better than just as a casual acquaintance.

No comments