Facebook All-in-One For Dummies, 2nd Edition (2014)
Book VI. Developing Facebook Apps
Chapter 4. Tour of the Facebook API
In This Chapter
Finding technical information
Understanding the Facebook API core concepts
Using Facebook SDKs
Placing Facebook objects on your website with social plugins
Developing apps for the Facebook platform requires a little knowledge on two fronts. The apps themselves often consist of HTML and CSS for creating and formatting websites, as well as JavaScript, PHP, Python, or Objective-C programming. To deploy an app on Facebook and take advantage of all the various objects, such as news feeds and other Facebook features, you need to have an understanding of the basic Facebook application programming interface (API).
Facebook provides a well-developed API for creating apps, with plenty of tools to help you integrate your app into Facebook’s social fabric, as well as extensive documentation. However, like most documentation (usually written by technogeeks), finding information isn’t always easy. Using it can be difficult, especially if you don’t know what to look for.
In this chapter, we take a look at the API and its core concepts, the various development tools, and the documentation — where to look for each tool and where to find detailed instructions on how to use them. In many instances, the Facebook documentation includes detailed deployment information, as well as online tools that create some of your app code for you — the parts of the code that integrate your app with the API, anyway.
Consider this chapter the tourist guide for using the Facebook API, including a map for finding the documentation for developing and deploying your Facebook apps.
Finding Technical Information
No matter how you slice it, just like creating apps for any other platform, developing Facebook apps is a highly technical undertaking — an expedition up Geek Creek. You know what they say about going up Geek Creek without a paddle, so remember that your paddle is Facebook’s online developer’s documentation, as well as a few other resources.
Like all aspects of information technology, Facebook changes frequently. The Facebook interface and features are under constant development, as is the site’s app technology and developer interface. In many cases, sometimes the only current documentation is the site’s online manual, which is usually updated with the site itself.
Facebook’s online API documentation
Because Facebook apps can do so many things, and can run from the very simple to the highly complicated, writing a step-by-step tutorial isn't useful. The online documentation for the Facebook API is divided into topics; in this section, you discover where to find technical information on some of the more important app development topics.
Where to start
In Book VI, Chapter 3, we provide a step-by-step exercise on installing a simple app in the Facebook API. That exercise is basic. You can get more detailed information at the following locations:
· Getting Started, Canvas Tutorial: Complete with code samples, this section, shown in Figure 4-1, provides information on creating your app, installing it on Facebook, authorizing it, and exploiting social channels (such as the news feed and game stories). You can also find a link to a sample app that uses real-time updates as one of its Facebook integration features. You can get to this page at https://developers.facebook.com/docs/guides/canvas/.
Figure 4-1: Much of Facebook’s app development documentation starts at this page.
· Getting Started, Apps on Facebook: This page provides an overview of the app-creation process, describing the canvas page, social channels, and analytics. Analytics enable you to gauge the performance of your app in terms of how often it gets used, who is using it, and so on. This page is located at https://developers.facebook.com/docs/appsonfacebook/tutorial/.
Advanced API documentation
The more sophisticated your apps become, the more you need to know about core concepts, Facebook’s software development kits (SDKs), and other advanced topics, such as dialogs and ads. You can get detailed information on the following Facebook documentation pages:
· Core concepts: Core concepts include social plugins, social channels, and authentication. We talk more about these later in this chapter in the “Social channels” and “Authentication” sections. You can get detailed information about core concepts athttps://developers.facebook.com/docs/coreconcepts/.
· SDKs and other tools: Facebook’s SDKs enable you to add functionality through JavaScript and PHP, as well as write code specific to Apple iPads and iPhones and mobile devices that use Google’s Android platform. Other Facebook API tools include the Developer App, debugging options, and a JavaScript test console. You can find a gateway page to these tools located at https://developers.facebook.com/tools/.
Third-party technical information
In addition to Facebook’s extensive developers’ manual, several other publications and websites are available to help you in creating and deploying apps. Here are a few we have found helpful:
· Facebook Application Development For Dummies by Jesse Stay (John Wiley & Sons) covers Facebook app development from start to finish. It includes such topics as which scripting languages to use, OAuth 2.0, real-time objects, and the Search API, as well as how to develop and sell business apps. We found this book quite helpful.
· Top 10 Facebook Apps for Building Custom Pages and Tabs on Social Media Examiner (www.socialmediaexaminer.com/top-10-facebook-apps-for-building-custom-pages-tabs/) showcases several apps that help you with creating page tabs and Facebook pages. These apps create fancy pages and multiple tabs on pages, and write HTML and other code for you to help spruce up your Facebook pages. They install directly into your Facebook account and provide extensive help in these and several other processes.
Helpful tutorials
In addition to the canvas tutorial described in the earlier section, “Where to start,” the folks at Facebook provide several other online tutorials on topics such as creating page tabs and games. Here are a few that we found helpful:
· Page tab tutorial: You can get a more detailed description of this process in the tutorial located at http://developers.facebook.com/docs/appsonfacebook/pagetabs/.
· Games tutorial: Game apps are popular on Facebook. A well-designed game can drive traffic to your Facebook account. For a detailed explanation of creating game apps, go to http://developers.facebook.com/docs/guides/games/.
· Fluid canvas tutorial: A fluid canvas adjusts its size to the browser window and screen resolution. For a detailed tutorial on making your canvases fluid, try http://developers.facebook.com/docs/fluidcanvas/.
Understanding Facebook’s Core Concepts
Building Facebook apps requires an understanding of Facebook's core concepts — the building blocks upon which you develop your apps. In this section, you take a quick look at these core concepts so that you can gain a broader understanding of app development.
One of the core concepts is social plugins. These Facebook apps are deployed on your website with links back to Facebook, instead of being deployed from your website to Facebook. Although Facebook lumps them in with the core concepts for app development, we discuss them in a separate section, “Placing Facebook Objects on Your Web Pages with Social Plugins,” later in this chapter.
Open Graph versus Graph API
According to Facebook cofounder Mark Zuckerberg, the social graph is the network of connections and relationships between the people on Facebook. The objects in the social graph are people, events, photos, pages, and so on. The network is the connection between these objects. Your apps exploit these objects from within and from outside Facebook.
Although highly simplistic, Figure 4-2 shows a visual representation of the social graph for one user’s Facebook account.
Figure 4-2: This Facebook app shows a visual representation of Facebook’s social graph.
Also called the Open Graph protocol, Open Graph started in 2010 allowing people to Like third-party, or non-Facebook, websites and pages. Perhaps the most common use for this protocol is the Like button on a blog post. Open Graph has been expanded to allow third-party sites and pages to interact with several Facebook actions and objects, as well as non-Facebook actions and objects within the app. Put simply, Open Graph is the social graph open to access from websites outside Facebook.
Graph API differs from Open Graph in that it represents objects within the Facebook API, such as people, events, and pages. Every object in Facebook — each photo, each person, each event, each app — is assigned a unique ID. Your apps can access and use these objects by referencing their IDs. Some objects have number IDs and are referenced like this: "id": "19292868552". Other objects have alpha, or word, IDs, and are referenced as follows: "username": "dannyt". In simple terms, the Graph API presents and represents objects on Facebook.
Requesting access to and accessing objects
Before your apps can access a user’s information and other objects associated with an account, the app must be granted access to these objects. Your apps request access to objects through authentication. Your app in turn accesses the objects and potentially shares them with the user’s friends through social channels.
Authentication
The first time a user accesses your app, an Auth dialog box appears, as shown in Figure 4-3, asking the user for permission to actions and objects from the user's Facebook account. Which actions (writing to a timeline, uploading photos, and so on) and objects (news feeds, events, pages, and more) your app needs access to depends on what the app does inside the Facebook API — your app code dictates what permissions you need. You set up and deploy the Auth dialog box that your users see through the Auth Dialog settings form, as demonstrated in Chapter 3 of this minibook.
Figure 4-3: Example of the Auth dialog box requesting permissions from a user.
Social channels
Most social channels work in third-party websites, as well as in apps on Facebook. Note, though, that not all objects are social channels. A photo, for example, is an object, but because it isn’t used as a vehicle for passing data from one user to another, it isn’t a channel. The Like button, on the other hand, facilitates the flow of information from one user to another (or to many others), making it a social channel. Social channels include the following objects:
· Feed dialog box
· Feed graph object
· Like button
· Request dialog box
· Bookmarks
· Notifications
· Dashboards
· Usage stories
· Search dialog box
Cool core tools for creating advanced apps
Facebook provides several tools for creating highly sophisticated apps — apps that post to users’ timelines, add tabs to user pages, prompt users to add friends, query and display information from databases, collect funds, initiate chat sessions, and many other functions. The following list takes a look at some of the more commonly used tools and what features they can add to your apps:
· Ads API: Part of the Graph API, the Ads API allows you to place advertisements in your apps or create apps that generate and manage ads on Facebook. To use this tool, you must apply and meet certain criteria. You can find out more about the Ads API athttp://developers.facebook.com/docs/reference/ads-api/.
· Chat API: You guessed it. This tool allows you to integrate Facebook Chat into other chat applications, such as instant messaging apps, web-based chat apps, and mobile instant messaging apps. You must use the Jabber/XMPP service to make the connection between Facebook Chat and your application. To find out more, check out https://developers.facebook.com/docs/chat/.
· Dialog boxes: Dialog boxes are used for just about everything on Facebook, including apps that collect payments. You can use Facebook dialog boxes in your apps, on third-party sites, and so on. There are several types of dialog boxes, including Friends, Feed, Pay, Request, and Send, and you can display them as pages, pop-ups, and in iframes. Find out more at https://developers.facebook.com/docs/reference/dialogs/.
· Facebook Query Language (FQL): If you’re familiar with database applications, you know about SQL. FQL differs from SQL in that it queries Graph API data instead of a SQL database. Most of the query language is similar to SQL, although it isn’t nearly as robust in math and other functions. For a description of how queries are formatted and which Graph API tables you can query (and how), go to http://developers.facebook.com/docs/reference/fql/.
· Internationalization API: This API translates your app (or website) among the 70 languages Facebook supports. Pretty cool, right? Be forewarned, though: Even for apps built in Facebook canvas pages and iframes, the translation is not automatic and must be set up for each language you want to use. Find that information at http://developers.facebook.com/docs/internationalization/.
XFBML — the Facebook markup language
Similar to HTML, XFBML (eXtended FaceBook Markup Language) allows you to integrate Facebook functions into your apps and web pages. XFBML contains special tags that call up Facebook actions and objects, such as Like buttons and Comment dialog boxes. These special tags provide a more robust integration with Facebook than iframes, which are discussed in Chapter 1 of this minibook.
Why does XFBML provide a more robust integration with Facebook than do iframes? For example, if you deploy a Like button by using XFBML, you can also include a Send button, which allows users to send messages to selected users about your pages (or anything else they want). In other words, XFBML simply gives you more options than iframes.
To use XFBML, your apps and web pages must load the Facebook JavaScript SDK library (discussed in the “Developing Apps More Easily with SDKs” section in this chapter). To use XFBML in your apps and pages, you place the XFBML tags in your page and enter the code that loads the required Facebook JavaScript SDK. The SDK interprets XFBML tags for the browser, thereby allowing the page to perform Facebook actions and exploit Facebook objects.
The good news is that for many objects, you don’t have to learn XFBML to use it. As discussed in the “Placing Facebook Objects on Your Web Pages with Social Plugins” section in this chapter, Facebook provides many code generators for most of the more common objects, such as Like buttons and Comment dialog boxes.
Developing Apps More Easily with SDKs
Facebook’s SDKs perform two important functions. Depending on the SDK, they load libraries of scripting functions that browsers can use to execute script code not otherwise available to the browser, or they provide programming environments that make writing code for a specific platform, such as Apple’s iOS mobile platform, easier. Some SDKs perform both functions.
Facebook has five SDKs, two for writing code in popular web-scripting languages (JavaScript and PHP), and two for writing platform-specific code for iOS (iPods, iPhones, and iPads), and Google’s popular Android operating system (OS) used on many smartphones and tablets. For the sake of this discussion, we separate the SDKs into two categories, placing the web-scripting language SDKs in one group and the OS SDKs in the other.
Typically, web-scripting languages are used for web apps, and OS SDKs are used for creating mobile apps, or standard apps that don’t usually require a web page to run in. You probably already have several mobile apps running on your smartphone or tablet.
Web-scripting SDKs
The two most popular scripting languages on the web are JavaScript, a client-side language, and PHP, a server-side language. Client-side scripts are executed by the browser, and server-side scripts are run by the server. Each has pluses and minuses. PHP, for instance, is better at data manipulation, such as querying databases and displaying data. JavaScript works better for visual and behavioral effects, such as simple animations, and displaying menus and buttons.
Another advantage to server-side scripts is that the server processes the code, removing much of the stress from the browser and device resources, which can be beneficial on mobile devices. In addition, JavaScript is not supported on all mobile devices, especially older smartphones and feature phones. Server-side scripts can help ensure that your pages and apps work on a wider range of devices.
Facebook’s JavaScript SDK
The JavaScript SDK supports client-side calls to Facebook’s server-side API, allowing your apps and web pages to take advantage of most Facebook features, including the Graph API and dialog boxes. It also processes XFBML for exploiting social plugins (discussed in the “Placing Facebook Objects on Your Web Pages with Social Plugins” section, later in this chapter), as well as providing a mechanism for your canvas pages to communicate with Facebook.
To use the Facebook JavaScript SDK, all you have to do is load it on top of your web pages and canvas pages. Your app can then use XFBML to interact with the Facebook API. Depending on what your app does inside Facebook, each application will require slightly different code to load the SDK. The basic script for loading it goes below the <body> tag in your pages and looks like Listing 4-1.
Listing 4-1: Loading the JavaScript SDK
<div id="fb-root"></div>
<script>
window.fbAsyncInit = function() {
FB.init({
appId : 'YOUR_APP_ID', // App ID
channelUrl : '//WWW.YOUR_DOMAIN.COM/channel.html', // Channel File
status : true, // check login status
cookie : true, // enable cookies to allow the server to access the session
xfbml : true // parse XFBML
});
// Additional initialization code here
};
// Load the SDK Asynchronously
(function(d){
var js, id = 'facebook-jssdk'; if (d.getElementById(id)) {return;}
js = d.createElement('script'); js.id = id; js.async = true;
js.src = "//connect.facebook.net/en_US/all.js";
d.getElementsByTagName('head')[0].appendChild(js);
}(document));
</script>
You can get detailed information on the JavaScript SDK from http://developers.facebook.com/docs/reference/javascript/.
PHP SDK
Because the PHP SDK loads server-side scripts, it consists of several PHP pages that you download from github (https://github.com) and upload to your web server (the server that hosts your app or web pages on which you want to include Facebook objects).
To use the PHP SDK, you need to acquire an app ID from Facebook’s developer app, which we show you how to use in Chapter 3 of this minibook. You need a lot more info to set up and use this SDK, which you can find athttp://developers.facebook.com/docs/reference/php/.
Mobile app–scripting SDKs
Facebook also provides SDKs for popular mobile devices, such as Google's Android operating system (OS), found on many of today's smartphones and tablets, as well as Apple’s iOS, used on iPhones, iPod touches, and iPads.
iOS SDK
The iOS SDK allows you to create apps for Apple’s handheld devices: the iPod Touch, iPhone, and iPad. Like the PHP SDK, the iOS SDK must be downloaded from github (https://github.com). You must also register it with Facebook and install it, which requires an app ID that you acquire from Facebook.
Technically, the iOS SDK is a Facebook app itself. As shown in Figure 4-4, it contains dialog boxes and debugging tools to help you through the app development process, but it does not completely eliminate the need for programming skills. The URL for the iOS Getting Started page, which contains links to multiple other iOS SDK technical documents, is at https://developers.facebook.com/docs/mobile/ios/build/.
Figure 4-4: The iOS SDK provides an environment for developing apps for Apple’s mobile devices.
Android SDK
The Android SDK allows you to develop Facebook apps for mobile devices (smartphones and tablets) that run on Google’s popular Android OS, which powers hundreds of devices. You must download the Android SDK from github (https://github.com), register it with Facebook, and install it.
If you’ve used Google’s Android SDK, you'll see some similarities in this one. As shown in Figure 4-5, the Android SDK provides several dialog boxes for walking you through the development process, including a code editor, a debugger, and a compiler. You can get full installation and usage details for the Android SDK at https://developers.facebook.com/docs/mobile/android/build/.
Figure 4-5: The Android SDK provides an environment for developing apps for Android-based devices.
Placing Facebook Objects on Your Web Pages with Social Plugins
The Facebook API provides a platform for developing apps that integrate and interact with Facebook, both inside the Facebook API and from third-party websites. Social plugins allow you to add Facebook objects to your web pages. A common application for social plugins is placing Like buttons on blog posts.
If you’ve used Facebook for more than a minute, you’re familiar with most of the objects you can control with social plugins, including the Like, Send, and Subscribe buttons and comments, the activity feed, and recommendations.
You can implement most plugins with either the XFBML or iframe technologies. The latter, iframe, is discussed in Chapter 1 of this minibook. Similar to HTML, XFBML formats your app web pages. (XFBML requires the JavaScript SDK.) For an explanation of XFBML, see this chapter’s sidebar, “XFBML — the Facebook markup language.” To find out more about the JavaScript SDK (and other Facebook SDKs), see the “Developing Apps More Easily with SDKs” section, earlier in this chapter.
To implement social plugins in your pages, you need to write some code. Facebook provides code generators for most social plugins. All you have to do is provide some basic information in the code generator forms, click the Get Code button, and copy and paste your code into your page. Figure 4-6 shows the Like button code generator. The page located at http://developers.facebook.com/docs/plugins/ provides links to pages containing social plugin code generators.
Figure 4-6: Facebook’s code generators automatically create the code for deploying social plugins in your pages.
Embedded Posts
The embedded posts plugin allows you to share any post on Facebook on a website or a Facebook app. This plugin can be useful for sharing a notable post in your blog or when you are trying to drive more engagement to a Facebook page post from your company’s website.
Activity feed
The activity feed plugin displays recent Facebook activity on your site. The activity feed can contain information about users interacting with content in your site, such as Like, Read, and Play. Comments also show up in the activity feed. What the user sees depends on whether he or she is logged in to Facebook. When logged in, the user sees activities from his or her friends. When logged out, the user sees recommendations (discussed later in this section) from your site and is provided with an opportunity to log in to Facebook.
Comments button
The Comments box allows users to, you guessed it, comment on your page. If the user doesn’t deselect the Post to Facebook check box, the comment is posted to news feeds of the user's friends, which is a terrific way to promote your site.
Facepile
The Facepile plugin displays profile pictures of Facebook users who have connected with your page in one way or another. You can configure it to display the pictures of people who have signed up for your site, people who have Liked your site, and so on. The images are tiled in your Like box.
Like box
The Like box, which appears on external web pages, differs from the Like button in that the Like box provides information about your web page, such as how many users have Liked this web page, as well as which of their friends have Liked it. Users also see recent posts from the web page and can Like the web page from within Facebook without having to go to the page. You can include several options, such as faces and profile streams, as shown in Figure 4-7.
Figure 4-7: An example of a Like box and the code generator used to create it.
Like button
When the user clicks the Like button for your external web page, a connection is created between your web page and the user. Your web page will appear in the Likes and Interest section of the user's timeline. You can also target ads to the people who have Liked your web page.
Share button
The Like button shows that the user liked your web page on Facebook, but the Share button actually shares a new entry on the person's timeline that links back to your website. This feature can sometimes be more effective at driving traffic than a Like button. As always though, measure to see which one performs better.
Recommendations box
The recommendations box shows personalized recommendations to your users. Recommendations are generated by all the social interactions with URLs from your site. A recommendation might look something like this: “Your App Name,” with a link to the app. The next line might read, “1,000,000 people recommended this.”
Note that recommendations are generated by domain or multiple domains specified in the plugin. You can get an explanation of how to implement this feature at http://developers.facebook.com/docs/reference/plugins/recommendations/.
Recommendations bar
The recommendations bar works like the recommendations box but sends real-time updates of suggestions for users to a bar at the bottom of your website. With the recommendations bar installed, users can both Like each page of your website from the bar and get individualized recommendations for each page of the site. You can also configure the bar so that recommendations appear a few seconds after a person visits each page of your website.
Registration
The registration plugin allows visitors to your site to sign up for your pages with their Facebook accounts. As shown in Figure 4-8, the plugin creates a form on your page and prefills it with information from the user’s Facebook account. You can choose to use several Facebook object fields for information or just a few. There’s also an option to allow the user to sign up through your registration process, just in case the user doesn’t want to use Facebook credentials, eliminating the need for separate forms.
Figure 4-8: An example of the Facebook registration form, which allows users to use Facebook credentials to register for your site.
Send button
Including a Send button on your external web page allows users to send content to friends. They can, for example, send the URL for your web page in a message or in an e-mail. The Send button differs from the Like button in that it allows users to send content to selected users, instead of to all their friends.
Follow button
Placing a Follow button in your web page lets users subscribe to your public updates. As part of the Follow button implementation (with JavaScript), you tell your app to listen in real time for clicks on the Follow button, which informs you immediately when a user subscribes.
Registration plugin
The registration plugin gives you a simple way to sign up users on your website using just their Facebook profile. The users log in to Facebook, and Facebook automatically detects their username and prepopulates fields that you can then use in your website either to store for later use or to customize the experience. To learn more about this plugin, go to https://developers.facebook.com/docs/plugins/registration/.