Facebook API Integration By Michelle Sollicito ECSTeam Atlanta, GA
Social networking is increasingly becoming a key component to developing deep relationships with customers. Social media is a powerful means of discovering trends, gaining feedback from customers, interacting with customers and their “friends” and marketing to customers in various ways. http://www.businessnewsdaily.com/815-social-media-2012.html Now integrating such social media data with internal systems is becoming increasingly important – especially with CRM systems and data mining/analytics systems, but also with product catalogs and shopping carts to provide a more personalized experience for users based upon their social media preferences. http://data-informed.com/4-approaches-for-integrating-social-media-data-with-enterprise-systems/ Recognizing this, Facebook has provided an open source set of apis providing access to Facebook data – the Graph API, Chat API, Credits API and Ads API. The Graph API is the api most useful for data integration as it provides access to information about people, their posts, their comments and their likes. This paper aims to explain how to use the Facebook Graph api effectively to integrate such data into internal business systems.
1. Introduction This paper will first introduce the Facebook Graph API and the different tools that are available when using it. It will then illustrate how to set up authorization and access to the API and the different types of authorization and access available to programs. Then a real “data extraction” example will be provided of how to retrieve posts from a Facebook group and place that data in a database table. An example of how to automatically post to a Facebook group will also be provided.
2. Trends Trend towards using social media to deepen relationships. People are buying via social media, are getting recommendations via social media, are reading feedback on products on social media, are learning about alternatives on social media, are trying to self service or get support on social media. Companies are realizing the value of the data and need to integrate it into their internal systems, especially their CRM systems.
Example: Utilities and social media Utilities want to educate their customers about the products and services they offer. They want to be Corporate Citizens, helping customers with their electrical appliances, helping
them during financial difficulties to keep their electric or gas on, helping them to budget effectively, helping them to reduce their bills, but most importantly they want to help customers when an outage happens – help them to quickly report outages, help them to find out how long an outage might last and to cope without the electricity/gas for the (hopefully short) period of time they are without it. During the snowstorms in Atlanta, utility customers shared information on the SnowedOutAtlanta Facebook group about how prepared (or otherwise) they believed their power company to be. They uploaded photos such as this one:
1. Using Facebook to communicate about companies
They shared information about how to prepare for power outages:
2. Using Facebook to help others self support
..and they watched the total of outages growing as the storm got worse over time..
3. Using Facebook to evaluate company performance
As a result of the huge Facebook activity during the snowstorms, the utility companies recognized the need to integrate Facebook data into their internal systems in order to effectively monitor their relationships with their customers.
3. Problem Integrating data from Facebook into internal systems is made easier because Facebook made available the Facebook Graph API but it does not solve the whole problem. Security is one of the biggest issues involved in Facebook data integration. In order to obtain the activity data from Facebook, one of two types of security gateways must be used. Either the Facebook user must “allow” an app to link their Facebook profile to the Internal data profile (and allow that app to extract certain kinds of data from their profile), or the Facebook user must post to a Facebook group or page owned by the company in question. The app itself must also have been set up with an authentication key that is appropriate to the context in which the app will be used. Facebook solves this problem using OAuth, a popular open authorization protocol which allows applications to access each other’s data. For more information about OAuth (version 2 is the current version) see http://tutorials.jenkov.com/oauth2/index.html To see how the process of authorizing an app to access Facebook data looks to the user, see an example here http://www.wikihow.com/Authorize-an-App-to-Connect-withFacebook Take note in particular of step 9 where the user is informed of the type of information being authorized (in this case, your public profile, friend list and email address):
4. Prompting the user for permission to access their data
If a user voluntarily joins a company Facebook group or Facebook page and posts information, it is a little easier to gain access to that data because by joining the group or page, the user has in effect provided authorization to the company to own that data. In this case, the application needs an app id and an authorization key in order to request access to the Facebook page or Facebook group (again different types of data may be requested) but once the application has been granted access it can read or post to that page/group depending upon the requested access type. Authentication is also an issue with the Facebook api in the sense that it can be difficult to associate a Facebook profile with an existing customer in the company database. In cases where the user explicitly allows the app to link the Facebook profile to the internal customer account, this problem is resolved. However, in cases where the Facebook user is just one of the users in a Facebook group or page, the usual way to link the user’s profile to a customer record in the database is via the email address associated with the Facebook account. Of course, if the primary email address on the Facebook account does not coincide with the email used to identify the customer in the internal database, it is possible that social media data could be accumulated under the wrong different “dummy” customer account. However, the social media data will still be useful, and it is possible to use other mechanisms to flush out these disparities.
4. Getting Started 4.1 Creating a Facebook App To create a Facebook app, first login to Facebook and go to your home page. Then type into the url: https://developers.facebook.com/ Click on “Apps” and then select “Create a New App” from the submenu.
5. Apps menu on Developer page
Enter a Display Name (this is the name that will be listed for your app under “Apps” on users’ Facebook pages so choose carefully! Choose a Namespace – this might be your company name for example – but be careful to have no capital letters in the Namespace due to naming conventions. If it is not a test version of another app, leave the No highlighted. Then select a category for your app. In this case, “Apps for Pages” is the correct category.
6. Creating an app
As soon as you create your app, your app is assigned an app id and a secret, see below. These are very important and you should take note of them now as you need them later. You can see the App Secret if you click on Show (you may have to enter your Facebook password in order to do that). Take a good look around the Dashboard while you are here as it can be very useful later as your apps grow and develop, and gain more of an audience.
4.2. Granting App Permissions
7. The app dashboard
The Status & Review section, for example, is very important because it is where you request permission for your app to collect different kinds of data. For example, if you want to post to a group or page using the app, you will need “manage_pages” permission in order to get an access token (security key) to allow you to access the page/group, and you will need “publish_actions” permission to allow your app to actually post posts to the group or page. For more information about permissions your app might need and why, see this article https://developers.facebook.com/docs/facebook-login/permissions/v2.0 Request the permissions you need here now before moving on.
8. Granting permissions to an app
5. Access Tokens The next thing you need to do is to generate a security access token. In order to do this, it is important to first understand how access tokens work. 5.1 Types of Facebook Access Tokens Firstly, it is important to know a little of the basics of OAuth 2.0 which is the protocol used by Facebook for security purposes. The general principle of OAuth is that a “http get” call is made to an OAuth uri indicating which permissions are required in the “scope” parameter, and the app requesting the permissions is identified using the “client_id” parameter. A “redirect_uri” parameter indicates which url to redirect to on successful grant of the permissions identified. There are four types of access token available to developers at this time via the OAuth mechanism.
The User Access token is used to obtain information about the user by prompting the user with a dialog and asking the user for permission to access their data, as illustrated in illustration 4., above. This kind of token can only be generated with permission from the user and requires user interaction. The App Access token is used to modify the settings for an app, and requires a server to server call using a pre-agreed secret. The Page Access token is used to read, write and modify information on or related to a Facebook page. It can be a little confusing, because you cannot obtain a Page Access token until you have first obtained a User Access token for the user who owns that page, and have been granted the “manage_pages” permission for that user. Note that for now, Page Access tokens can also be used to manage groups, though it is possible that will change in future versions of the Facebook API. The Client Token (AppId) is a unique identifier used to identify a particular app or application. It is embedded into the app or application and is used to access app-level APIs. You can see the AppId on your dashboard. In addition, there are two types of User Access tokens – short-term and long-term tokens. Short-lived User Access tokens typically expire after a couple of hours and are generated via web logins, similarly to in illustration 4., above. Long-term User Access tokens are obtained using a short-lived User Access token, an app id and the app secret combined, and are used time and time again by the same application over a longer period of time. Long-term User Access tokens typically expire after XXXX A typical generic get call that will return a short-lived User Access token looks something like this, and must always be made server side for security reasons (anyone who can see this call containing your app id, app secret and a short lived token, could potentially use the long-term token generated to do anything they wanted to to your Facebook page)::
GET /oauth/access_token? client_id={app-id} &client_secret={app-secret} &grant_type=client_credentials
It is possible to avoid generating and using app access tokens. You can send in the app_id and the app_secret instead, see below:
http://graph.facebook.com/endpoint?key=value&access_token=app_id| app_secret
A typical generic get call that will return a long-term User Access token looks something like this, and must always be made server side for security reasons (anyone who can see this call containing your app id, app secret and a short lived token, could potentially use the long-term token generated to do anything they wanted to to your Facebook page):
GET /oauth/access_token? grant_type=fb_exchange_token& client_id={app-id}& client_secret={app-secret}& fb_exchange_token={short-lived-token}
5.2 OAuth with Facebook A typical direct Facebook OAuth call looks like this (in this case to get the access token for an application with the “manage_pages” permission): https://www.facebook.com/dialog/oauth? client_id=APPLICATION_ID&redirect_uri=https://www.facebook.com/connect/login_su ccess.html&response_type=code+token&display=popup&scope=manage_pages If you want to capture the result (access token) programmatically, you can add &type=user_agent or &type=web_server to your OAuth call to receive the result as a parameter in the url of the redirect page either like this: http://yourredirecturi#code=[accesstoken] Or like this: http://yourredirecturi&code=[accesstoken] A typical OAuth request in C#/.Net (using the Facebook SDK for .Net, available here http://facebooksdk.net/ or via Nuget) for reading the “stream” from a user’s groups looks like this: string AppID = "[put your appid here]"; string AppSecret = "[put your app secret here]";
// using Facebook SDK for .NET to read from groups var fb = new Facebook.FacebookClient(); dynamic result = fb.Get("oauth/access_token", new { client_id = AppID, client_secret = AppSecret, grant_type = "client_credentials", scope = "user_groups,read_stream", redirect_uri = redirectUrl }); app_token = result.access_token;
This is an example of requesting permissions to post to a user’s groups: // using Facebook SDK for .NET to post to groups var fb = new Facebook.FacebookClient(); dynamic result = fb.Get("oauth/access_token", new { client_id = AppID, client_secret = AppSecret, grant_type = "client_credentials", scope = "user_groups,publish_stream", redirect_uri = redirectUrl }); app_token = result.access_token;
In this case the app token returned provides the app with the permissions to read all the user groups associated with that app. PHP and Python code for using OAuth 2.0 is provided here: http://hayageek.com/facebook-dialog-oauth/ To find out more about access tokens see this page: https://developers.facebook.com/docs/facebook-login/access-tokens For more detail about how OAuth 2.0 works in Facebook see https://developers.facebook.com/docs/reference/dialogs/oauth For a more general introduction to OAuth, as stated before, a great tutorial to provide a basic understanding is this one: http://tutorials.jenkov.com/oauth2/index.html It should be noted many respected web services providers including twitter, Yahoo! and Google all use OAuth 2.0 as their authentication protocol.
Be aware that even long-term access tokens eventually expire and this article explains how to handle those situations: http://facebooksdk.net/docs/web/handling-expired-accesstokens/ 6. Finding Your Page Id or Group Id Once you have the access token, you are going to need to know the id of the resource for which you want to find information – in this case it will be the Page Id or the Group Id. If you do not know your page id for your Facebook page or group, the best way to find it is to do the following: 1) Go to the url of your Facebook page. For example, it might be something like this: https://www.facebook.com/groups/snowedoutatlanta/ or it might be something like this: https://www.facebook.com/groups/236592123131746/ or a page may have a url like this: https://www.facebook.com/TxtToAd 2) From the Page or Group main page, go to the “Report Group” option under the “Gear” icon see below
Hover over the “Report Group” option and right click your mouse and select “Copy link address”. Paste the contents of your clipboard into notepad or similar. You should get something that looks like this: https://www.facebook.com/ajax/report.php? content_type=1&cid=397839673695382 The cid parameter contains your Page Id. So, in this case, the Page Id is 397839673695382.
Note that there are many other ways to get your Page Id but this one consistently works (others work in some circumstances but not in others). 7. Testing URLs In order to determine the urls needed within your code it is a good idea to first get acquainted with a wonderful tool provided by Facebook to help with generating calls to the Graph API. It is called the “Graph API Explorer” and makes working with the Graph API a great deal easier. To see it in action go to this url: https://developers.facebook.com/tools/explorer You should see something that looks like this:
Note that it automatically creates a short-term access token to be used during the session at the top of the page.
Also note that it works in two modes: Graph API and FQL Query. During this tutorial we will mainly use the Graph API because FQL will soon be retired/discontinued, but the FQL Query is/was an extremely powerful SQL-like tool for querying Facebook objects and was very useful for quickly finding information so you may want to learn something about it, while bearing in mind that it will not be around forever: If you do, this is a great resource: https://developers.facebook.com/docs/reference/fql/ Using the Graph API mode, it is possible to test out urls and queries and see the kinds of results obtained. By default, the “me” query showing the currently logged in Facebook user’s id and name is provided.
Change the query from: /me?fields=id,name to: /[page id for your Facebook page]/feed to see the news feed for your Facebook page or Facebook group. For example, my SnowedOutAtlanta group feed query would look like this: /397839673695382/feed See below:
You will see that the main data returned is a group of “Post” objects. Post objects have properties such as “message”, “picture”, “link”, “name”, “caption” and “description”. For full details of the Post object, see this link https://developers.facebook.com/docs/graph-api/reference/v2.0/post For full details of the feed call, see this link: https://developers.facebook.com/docs/graph-api/reference/v2.0/page/feed For a general introduction to using the Graph API Explorer I recommend this link, although it is a little out of date it is still a very good overview. https://developers.facebook.com/blog/post/517/ The Graph API Explorer is a great way to try out different queries to the Graph API quickly and easily without having to write code. Once you are confident you have the correct URLs/queries, you can then go on to write your code in your chosen implementation language.
8. Writing the Code So now your app has permissions and a security access token, and you have an idea of the queries you want to write to get the information you need from Facebook, it is time to start writing code against the Facebook API. It is possible to write code using a multitude of programming languages. For illustration purposes, here we will produce some code in C# / ASP.Net and some code in javascript using XHR. Here is an example javascript function to retrieve the username field for a Facebook user, given the “userid”. The Facebook userid is the number that looks something like this: 100000449886864 (in fact if you call this function with the above userid, the username returned is “msollicito” (my facebook username). Note that this code uses the “user” Facebook API object referenced here: https://developers.facebook.com/docs/graph-api/reference/v2.0/user function getUserId(userid) { var url="https://graph.facebook.com/" + userid + "?fields=username"; var xhr = new XMLHttpRequest(); xhr.open("GET", url, false); xhr.onload = function (e) { if (xhr.readyState === 4) { if (xhr.status === 200) { struserid=xhr.responseText; } else { struserid=xhr.statusText; } } }; xhr.onerror = function (e) { struserid=xhr.statusText; }; xhr.send(null); } You can use javascript to retrieve posts from a group or page feed using the following url: var graphURL = "https://graph.facebook.com/[put your group or page id here]/feed?" + "callback=displayPosts&" + "date_format=U&" + "limit=5000000&access_token=[put your access token here]";
If you run the following code: // Call the Graph API here function getPosts() { var posts = document.createElement("posts"); posts.src = graphURL; document.body.appendChild(posts); } .. when the element “posts” is added to the page, that invokes the call to the graphURL which in turn retrieves some posts as data and sends the data as an object (postData) to the callback “displayPosts” referred to in the graphURL. The posts retrieved are, of course, posts from the group (or page) identified by the id placed into the url between https://graph.facebook.com/ and /feed?” “displayPosts” takes the post data, and if there are some posts in that data, it creates a new graphURL with a new parameter – until – indicating the time until which to retrieve posts, using the created_time of the last post previously retrieved. This new url will be used in the next fetch of the post data. Then it processes the data that came back during this fetch of the post data, getting the userid first (using the function we talked about earlier – getUserId) and then processing the Facebook API “Post” object – in this case, we are displaying updated_time, created_time and the message, but we could access any of the “fields” of the Facebook API Post object here, see https://developers.facebook.com/docs/graphapi/reference/v2.0/post for details. //display posts using Javascript function displayPosts(postData) { if (postData.data.length <2) { document.getElementById("divMore").innerHTML = "All posts retrieved"; } else { graphURL = graphURL + "&until=" + postData.data[postData.data.length-1].created_time; for (var post in postData.data) { getUserId(postData.data[post].from.id); var message = document.createElement("div"); message.innerHTML = totalcount + " " + "user:" + struserid + " last updated:" + new Date(postData.data[post].updated_time * 1000) + " created:" + new Date(postData.data[post].created_time * 1000) + "
" + postData.data[post].message + "
" ;
document.getElementById("content").appendChild(message); totalcount++; } setTimeout(displayPosts, 100); //let’s get the next lot of posts now } } Here is an example of some C# code that gets a feed url and processes the post objects returned: //url includes the pageid, access token and until date to limit the posts returned string URL = https://graph.facebook.com/ + PageId + “/feed?" + "limit=500000000&access_token=" + longtermapptoken + "&until=2014-08-08";
//get the stream returned by the URL
Stream stream = webClient.OpenRead(URL); //convert it to a string StreamReader streamReader = new StreamReader(stream); string strStream = streamReader.ReadToEnd(); //deserialize it var serializer = new JavaScriptSerializer(); var result = serializer.Deserialize
(strStream); //determine how many messages (posts in this case) are returned messages = result["data"].Length; Response.Write("Messages:" + messages); //process each message returned for (int i = 0; i < messages; i++) { FBCommon.FacebookPost fp = new FBCommon.FacebookPost(); try { try { fp.id = result["data"][i]["id"]; } catch (Exception ex) { fp.id = ""; } try { fp.message = result["data"][i]["message"] + ""; } catch (Exception ex) { fp.message = "";
}
}
Here is some C# code for reading in comments made to a specific post retrieved above – in this case, the comments are simply added to the main message of the Facebook post but they could be stored separately of course: try { fp.commentscount = result["data"][i]["comments"]["data"].Length; } catch (Exception ex) { fp.commentscount = 0; } Response.Write("Comments: " + fp.commentscount + ""); try { if (fp.commentscount > 0) { Response.Write("Adding comments to message
"); fp.message = fp.message + "
Comments
"; fp.comments = new Dictionary(); for (int comcount = 0; comcount < fp.commentscount; comcount++) { FBCommon.FacebookComments fc = new FBCommon.FacebookComments(); fc.id = result["data"][i]["comments"]["data"][comcount]["id"] + ""; fc.from = result["data"][i]["comments"]["data"][comcount]["from"] ["name"] + ""; fc.message = result["data"][i]["comments"]["data"][comcount] ["message"] + ""; fc.created_time = result["data"][i]["comments"]["data"][comcount] ["created_time"] + ""; fp.comments.Add(fc.id, fc); } } Response.Write("fp.message: " + fp.message);
} catch (Exception ex) { }
Once you have obtained the data as above, of course, the data can be stored in your database or Entity Framework model as you would store other data, and can thereafter be integrated with other data within your system. Here is a great tutorial for posting to a Facebook wall using C# and MVC: http://dotnetdevtricks.blogspot.com/2012/09/facebook-c-sdk-for-aspnet.html
And this one shows how to use AJAX calls with MVC: http://weblogs.asp.net/kon/getting-started-with-facebook-c-sdk
9. Conclusion This paper has illustrated in depth how to use the Facebook API to integrate Facebook data into back-end systems, including how to set up a Facebook app, how to authorize that app to access data and then how to access the data using various programming languages.
10. Additional Information and Links The full Facebook API reference is available here: https://developers.facebook.com/docs/graph-api/reference/v2.0/ Various SDKs to use when writing code against the Facebook API for different platforms/languages are available here: https://developers.facebook.com/docs/other-sdks Microsoft CRM add-on Parrot enables integration of social media info into Microsoft CRM Dynamics. http://pinpoint.microsoft.com/en-us/applications/social-crm-for-microsoft-dynamics-crmparrot-12884912469 Orcatec Decisioning Suite offers tools for analyzing social media by various metrics, such as over time, spatial network mapping of how information spreads between users, etc. http://www.orcatec.com
About ECSTeam ECS was founded in 1999 with the vision that smart people working together with our clients can accomplish great things. This vision has enabled us to grow to over 100 professionals today. Our greatest assets are our people and the leadership we bring to projects. Our vision at ECS is to gather the best talent and leadership in the technology field, working in a team environment to provide the best service to our clients. We take tremendous pride in being a company our customers count on to deliver their business needs. They know we bring great people, strategy and execution to every engagement.
Michelle Sollicito was the creator and manager of the Fastest-growing Facebook Group in History, SnowedOutAtlanta – a group that helped save numerous lives in the Atlanta snowstorms in 2014, and she has 25 years’ experience in software development. Examples of typical white papers written by Michelle Sollicito http://www.txttoad.com/WorkDocs/CommerceServer2007_StagingWhitePaper.doc If you find this document useful, we would really appreciate it if you would share it on Facebook, LinkedIn, twitter etc. Contact information: Michelle Sollicito ECSTeam Phone: 678-357-3661 Email: [email protected] Website: http://www.ecsteam.com
