Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 110 lines (70 sloc) 12.121 kb
347798f Pat Patterson Added unmanaged package install to README
authored
1 # Force.com Toolkit for Facebook
6d8b6a5 Pat Patterson Added more detail to README
authored
2
347798f Pat Patterson Added unmanaged package install to README
authored
3 The Force.com Toolkit for Facebook allows your Force.com apps to manipulate the Facebook [Graph API](https://developers.facebook.com/docs/reference/api/). The toolkit provides a set of Apex classes, such as `FacebookUser` and `FacebookPost`, that model Facebook Graph API Objects such as `User` and `Post`.
6d8b6a5 Pat Patterson Added more detail to README
authored
4
98dfb9e Pat Patterson Corrected URL for sample site
authored
5 There is a sample deployment of the toolkit at https://testfbtk3-developer-edition.na14.force.com/ - you can visit this Force.com Site, login via Facebook, and see the toolkit in action. All the code behind the sample site is included in the toolkit.
2c11a15 Pat Patterson Added note on sample site
authored
6
347798f Pat Patterson Added unmanaged package install to README
authored
7 ## Major changes in Version 3
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
8
347798f Pat Patterson Added unmanaged package install to README
authored
9 * There is a new custom object, `FacebookSession__c`, that associates the Facebook access token with a session cookie. This allows a Force.com Site to authenticate users via Facebook.
10 * The toolkit uses the new native JSON implementation, mitigating issues in earlier versions where JSON was parsed in an Apex utility class, which severely limited the amount of data that could be parsed.
4c1b38e Pat Patterson Update d README with TODO
authored
11 * TODO - add code to use Spring '12 Facebook Authentication Provider
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
12
347798f Pat Patterson Added unmanaged package install to README
authored
13 ## Installation
14
15 There are two mechanisms for installing the toolkit: as an unmanaged package, or from GitHub. Choose the unmanaged package if you will be using the toolkit to develop your own Facebook app. If you are considering modifying or extending the toolkit itself, then installing from GitHub is a little more work, but will enable you to easily contribute code back to the project.
16
17 ### Installing the Unmanaged Package
18
19 1. Create a new Developer Edition (DE) account at http://developer.force.com/join. You will receive an activation email - click the enclosed link to complete setup of your DE environment. This will also log you in to your new DE environment.
72d9475 Pat Patterson Update unmanaged package URL
authored
20 2. Install the unmanaged package into your new DE org via this URL: https://login.salesforce.com/packaging/installPackage.apexp?p0=04td00000001Hsg
347798f Pat Patterson Added unmanaged package install to README
authored
21 3. Click through the screens to complete installation.
22 4. Go to **Setup | Administration Setup | Security Controls | Remote Site Settings** and add https://graph.facebook.com as a new remote site.
23
24 ### Installing from GitHub
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
25
26 1. Create a new Developer Edition (DE) account at http://developer.force.com/join. You will receive an activation email - click the enclosed link to complete setup of your DE environment. This will also log you in to your new DE environment.
27 2. Create a new Force.com project in the [Force.com IDE](http://wiki.developerforce.com/index.php/Force.com_IDE) using your new org's credentials. In the 'Choose Initial Project Contents' dialog, select 'Selected metadata components', hit 'Choose...' and select ALL of the components in the next page. This will give you a complete project directory tree.
6d8b6a5 Pat Patterson Added more detail to README
authored
28 3. Clone this GitHub project into the Force.com IDE project directory. You will need to clone it first to a temporary location, since git will not let you clone to a directory with existing content:
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
29
17d874c Pat Patterson Updated git repo URL
authored
30 $ git clone --no-checkout git://github.com/developerforce/Force.com-Toolkit-for-Facebook.git /path/to/your/projectdir/tmp
6d8b6a5 Pat Patterson Added more detail to README
authored
31 $ mv /path/to/your/projectdir/tmp/.git /path/to/your/projectdir
32 $ rm -rf /path/to/your/projectdir/tmp
33 $ cd /path/to/your/projectdir
34 $ git reset --hard HEAD
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
35
36 4. In Eclipse, right click your project in the project explorer and click 'Refresh'. This causes Eclipse to scan the project directory tree for changes, and the plugin syncs changes to Force.com.
37 5. In your DE environment, go to **Setup | App Setup | Create | Apps**, click 'Edit' next to the Facebook Toolkit 3 app, scroll down, click the 'Visible' box next to System Administrator and hit 'Save'. Now go to **Setup | Administration Setup | Manage Users | Profiles**, click on 'Edit' next to System Administrator, scroll down to Custom Tab Settings, set 'Facebook Apps', 'Facebook Social Samples', 'Facebook Sessions' and 'Facebook User Connections Test' to 'Default On' and hit 'Save'. 'Facebook Toolkit 3' should now be available in the dropdown list of apps (top right).
38 6. Go to **Setup | Administration Setup | Security Controls | Remote Site Settings** and add https://graph.facebook.com as a new remote site.
39
347798f Pat Patterson Added unmanaged package install to README
authored
40 ## Configuring the Sample Force.com Site
6d8b6a5 Pat Patterson Added more detail to README
authored
41
42 1. Go to **Setup | App Setup | Develop | Sites** and create a new site. Set the home page to `FacebookSamplePage` and add `FacebookTestUser` to the list of Site Visualforce Pages. Ensure you activate the site.
43 2. Go to **Setup | App Setup | Develop | Apex Classes**, hit the 'Compile All Classes' link, then click 'Schedule Apex' and add `FacebookHousekeeping` - set it to run at midnight every night. This scheduled Apex job will remove expired session records from the FacebookSession__c object.
44 3. Go to the [Facebook Apps Page](https://developers.facebook.com/apps), click 'Create New App' and complete the required fields. Under 'Website', set Site URL to your site's secure URL - for example, https://fbtest-developer-edition.na14.force.com/
cdad0e0 Pat Patterson A little more detail on setting the app secret
authored
45 4. In your DE environment, select the 'Facebook Toolkit 3' app from the application menu at top right, then click the 'Facebook Apps' tab. Create a new Facebook app, copying 'App ID' from your new app's settings in Facebook. Set 'Permissions' to allow the sample app to access more data; for example, you might use `read_stream, publish_stream` to allow the app to read and write posts on the user's feed. See the [Facebook Graph API documentation](https://developers.facebook.com/docs/reference/api/permissions/) for a full discussion of permissions. Note that, after you save the Facebook App record, you must click the 'Set App Secret' button to enter the 'App Secret' from your new app's settings in Facebook.
6d8b6a5 Pat Patterson Added more detail to README
authored
46 5. Go to your site URL (e.g. https://fbtest-developer-edition.na14.force.com/) and you should be prompted to log in to your new app. Do so and you should see a sample page showing your Facebook user name, profile picture, feed, 'Like' button etc. There are buttons to dynamically retrieve your user profile and friends list.
47 6. Now you have the sample page working, you have a starting point for a Facebook app running on Force.com. Examine `FacebookSamplePage` and `FacebookSampleController` to see how the sample app is put together.
48
347798f Pat Patterson Added unmanaged package install to README
authored
49 ## Developing a Facebook App with the Toolkit
6d8b6a5 Pat Patterson Added more detail to README
authored
50
51 Every Facebook Graph API call must be accompanied by an *access token*; the access token authorizes your app to access the Graph API on behalf of the authenticated user. Facebook uses the [OAuth 2.0](http://oauth.net/2/) protocol for authentication and authorization. Your app must send users to Facebook to log in and authorize your app to access the Graph API on the users' behalf. There are two ways of doing this, depending on whether you want to map Facebook users to identities in salesforce.com.
52
53 ### No Mapping
54
55 You can implement your app as a Force.com Site, in which, as far as the Force.com platform is concerned, all users are mapped to a single Site Guest user. You must manage any user-related data yourself, typically indexed by users' Facebook IDs, and you must use the `FacebookLoginController` supplied with the toolkit as a base class for your app's controllers. `FacebookLoginController` manages the OAuth 2.0 interaction with Facebook, randomly generates a session cookie for the user, and maintains a `FacebookSession` custom object mapping session cookies to Facebook access tokens. Your Visualforce pages must set their action attribute to the controller's login method so that `FacebookLoginController` can obtain the access token:
56
57 <apex:page controller="FacebookSampleController" action="{!login}"
58 cache="false" sidebar="false" showHeader="false"
59 title="Force.com Toolkit for Facebook - Sample Page">
60
61 Your controller code can now retrieve the current user's token with `FacebookToken.getAccessToken()`.
62
63 ### Map Facebook Accounts to Salesforce Users
64
d079921 Pat Patterson More detail in the README
authored
65 Alternatively, from Spring ''12 onwards, you can implement your app within a Salesforce org or portal. In this case, each Facebook account is mapped to a unique user within your Salesforce org. [Social Single Sign-On – Authentication Providers in Spring ’12](http://blogs.developerforce.com/developer-relations/2012/01/social-single-sign-on-authentication-providers-in-spring-12.html) gives an overview of configuring Facebook as an *Authentication Provider* and linking existing salesforce.com users'' accounts to their Facebook accounts, or creating new accounts for users arriving from Facebook.
6d8b6a5 Pat Patterson Added more detail to README
authored
66
d079921 Pat Patterson More detail in the README
authored
67 If you are using the Facebook Authentication Provider, you need not use `FacebookLoginController`; the platform will manage interaction with Facebook for you. Your Apex code can retrieve the current user''s token with `Auth.AuthToken.getAccessToken(AuthProviderID, AuthProviderType);`.
6d8b6a5 Pat Patterson Added more detail to README
authored
68
d079921 Pat Patterson More detail in the README
authored
69 Since the main intent of this first, Spring ''12, release of Authentication Provider functionality is to provide single sign-on and account linking, there are some limitations in using the FB access token with the Graph API:
70
71 * The Facebook Authentication Provider requests only the `email` permission, limiting the amount of data you can retrieve via the Graph API to the user's email address, user id, name, profile picture, gender, age range, locale, networks, list of friends, and any other information they have made public. It is expected that developers will be able to set a custom set of requested permissions in a future release.
72 * The Facebook access token will expire after two hours. There is currently no mechanism for obtaining a fresh access token. One possible strategy for handling this issue would be to detect token expiry and offer to redirect the user to the Authentication Provider SSO link to reauthenticate to Salesforce.
6d8b6a5 Pat Patterson Added more detail to README
authored
73
74 ### Accessing the Graph API
75
76 However you obtain the access token, accessing the API follows the same pattern. You can retrieve most Facebook Graph API objects by calling the relevant constructor with the access token and an id (for example, `me`) or connection (for example, `me/friends`) and an optional map of API parameters.
77
78 So, to retrieve the `User` object for a user with Facebook ID 1111111111:
79
80 FacebookUser user = new FacebookUser(access_token, '1111111111');
81
82 and to retrieve a list of friends, including their hometowns, for the currently authenticated user:
83
84 Map<String,String> params = new Map<string,string>{'fields' => 'id,name,hometown'};
85 FacebookUsers friends = new FacebookUsers(access_token, 'me/friends', params);
86
87 Note that your app is limited to the data to which the authenticated user and other users have granted access.
88
89 Once your app has retrieved a Graph API object, it can manipulate it in Apex or Visualforce using its Apex properties. Here a Visualforce page iterated through the friends object obtained above:
90
91 <apex:pageBlockTable value="{!friends.data}" var="friend">
92 <apex:column value="{!friend.id}" headerValue="Id"/>
93 <apex:column value="{!friend.name}" headerValue="Name"/>
94 <apex:column value="{!friend.hometown.name}" headerValue="Hometown"/>
95 </apex:pageBlockTable>
96
97 You can see many similar examples in the sample pages and controllers:
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
98
6d8b6a5 Pat Patterson Added more detail to README
authored
99 * `FacebookSamplePage`
100 * `FacebookSampleController`
101 * `FacebookTestUser`
102 * `FacebookTestUserController`
cfaba4f Pat Patterson Cleanup before migration to native JSON
authored
103
a7cec55 Pat Patterson Check that user has Customize Application permission when setting encryp...
authored
104 ### Security Considerations
105
106 The toolkit AES-256 encrypts secrets at rest (Facebook application client secrets and user access tokens), dynamically creating a key on first use and saving that key in a protected custom setting. As a result, these secrets are secure when the toolkit is used in a managed package - the key is inaccessible outside the package, and can only be created when a user with the 'Customize Application' permission (for example, a user with the System Administrator profile) creates the first Facebook App record.
107
108 Note that, if the toolkit is used outside a managed package, these secrets are accessible to any users that can access the custom setting, either directly in the console, or indirectly via Apex code.
109
2379bff Pat Patterson Updated getting started link
authored
110 For more information, see the [getting started guide](http://wiki.developerforce.com/page/Getting_Started_with_the_Force.com_Toolkit_for_Facebook,_Version_3.0).
Something went wrong with that request. Please try again.