Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 240 lines (146 sloc) 12.323 kb
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
1 This open source Java library allows you to integrate Facebook into your Android application. Except as otherwise noted, the Facebook Android SDK is licensed under the Apache License, Version 2.0 (http://www.apache.org/licenses/LICENSE-2.0.html)
632b6e8 Update README with configuration changes and latest information
Steven Soneff authored
2
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
3 Getting Started
4 ===============
2cd0181 First draft of README file.
Luke Shepard authored
5
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
6 The SDK is lightweight and has no external dependencies. Getting started is easy.
2cd0181 First draft of README file.
Luke Shepard authored
7
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
8 Setup your environment
9 --------------------------
f592a66 Fix touch redirect issue
Steven Soneff authored
10
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
11 1. Pull the repository from GitHub:
f592a66 Fix touch redirect issue
Steven Soneff authored
12
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
13 git clone git://github.com/facebook/facebook-android-sdk.git
67edde3 Known issues section.
Luke Shepard authored
14
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
15 2. If you have not already done so, follow the (http://developer.android.com/sdk/index.html)[Android SDK Getting Started Guide]. You will need the device emulator and debugging tools.
67edde3 Known issues section.
Luke Shepard authored
16
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
17 3. The Facebook Android SDK works fine in any Android development environment. To build in Eclipse:
fc315c5 Updates to README
Steven Soneff authored
18
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
19 * Create a new project for the Facebook SDK in your Eclipse workspace.
20 * Select __File__ -> __New__ -> __Project__, choose __Android Project__ (inside the Android folder), and then click __Next__.
21 * Select "Create project from existing source".
22 * Select the __facebook__ subdirectory from within the git repository. You should see the project properties populated (you might want to change the project name to something like "FacebookSDK").
23 * Click Finish to continue.
632b6e8 Update README with configuration changes and latest information
Steven Soneff authored
24
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
25 The Facebook SDK is now configured and ready to go.
224adc6 Update known issues in the README
Steven Soneff authored
26
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
27 Sample Applications
28 --------------------
92a5425 Update known bugs in README
Steven Soneff authored
29
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
30 This library includes two sample applications to guide you in development.
2cd0181 First draft of README file.
Luke Shepard authored
31
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
32 * __simple__: A bare-bones app that demonstrates authorization, making API calls, and invoking a dialog.
2cd0181 First draft of README file.
Luke Shepard authored
33
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
34 ![simple](http://sphotos.ak.fbcdn.net/hphotos-ak-snc4/hs935.snc4/74854_172094179474325_109700069047070_612899_4026782_n.jpg)
2cd0181 First draft of README file.
Luke Shepard authored
35
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
36 * __stream__: This slightly beefier application lets you view your news feed.
2cd0181 First draft of README file.
Luke Shepard authored
37
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
38 ![stream](http://sphotos.ak.fbcdn.net/hphotos-ak-snc4/hs827.snc4/68752_172094172807659_109700069047070_612898_4403693_n.jpg)
2cd0181 First draft of README file.
Luke Shepard authored
39
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
40 To install a sample application into Eclipse (3.5):
0bcac3e Clarify git clone instructions in the README
Steven Soneff authored
41
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
42 * Create the sample application in your workspace:
43 2. Select __File__ -> __New__ -> __Project__, choose __Android Project__, and then click __Next__.
44 3. Select "Create project from existing source".
45 4. Choose either __examples/simple__ or __examples/stream__. You should see the project properties populated.
46 5. Click Finish to continue.
2cd0181 First draft of README file.
Luke Shepard authored
47
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
48 * Build the project: from the Project menu, select "Build Project".
2cd0181 First draft of README file.
Luke Shepard authored
49
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
50 * Run the application: from the Run menu, select "Run Configurations...". Under Android Application, you can create a new run configuration: give it a name and select the simple Example project; use the default activity Launch Action. See http://developer.android.com/guide/developing/eclipse-adt.html#RunConfig for more details.
2cd0181 First draft of README file.
Luke Shepard authored
51
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
52 Integrate with an existing application
53 -----------
2cd0181 First draft of README file.
Luke Shepard authored
54
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
55 The easiest way to get started is to copy/hack up the sample applications (that's what they are there for). However, if you want to just integrate the Facebook SDK with an existing application (or create a new one from scratch), then you should:
2cd0181 First draft of README file.
Luke Shepard authored
56
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
57 * Add a dependency on the Facebook Android SDK library on your application:
58 1. Select __File__ -> __Properties__. Open the __Android__ section within the Properties dialog.
59 2. In the bottom __Library__ section, click __Add...__ and select the Facebook SDK project.
60 3. Any issues? Check [Android documentation](http://developer.android.com/guide/developing/eclipse-adt.html#libraryProject)
2cd0181 First draft of README file.
Luke Shepard authored
61
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
62 * Ensure that your application has network access (android.permission.INTERNET) in the Android manifest:
1a44ca8 README clarifications
Steven Soneff authored
63
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
64 <code><uses-permission android:name="android.permission.INTERNET"></uses-permission></code>
2cd0181 First draft of README file.
Luke Shepard authored
65
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
66 * Register your application with Facebook:
67 1. Create a new Facebook application: http://www.facebook.com/developers/createapp.php . If you already have a canvas or web application, you can use the same application ID.
68 2. Set your application's name and picture. This is what users will see when they authorize your application.
fc315c5 Updates to README
Steven Soneff authored
69
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
70 Set up single sign-on
71 -----------
fc315c5 Updates to README
Steven Soneff authored
72
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
73 Optionally, you can make your login system more seamless by incorporating single sign-on.
2cd0181 First draft of README file.
Luke Shepard authored
74
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
75 * Register your application's Android key hash. This is used by Facebook to ensure that another app can't impersonate your app when talking to the Facebook Android app.
1a44ca8 README clarifications
Steven Soneff authored
76
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
77 1. Generate the key hash: <pre><code>keytool -exportcert -alias [alias] -keystore [keystore]
78 | openssl sha1 -binary
c1ba90f Updates to README for platform dialogs.
Jim Brusstar authored
79 | openssl base64</code></pre>
2cd0181 First draft of README file.
Luke Shepard authored
80
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
81 2. In the Facebook developer settings, go to the __Mobile and Devices__ tab.
82 3. In the __Android__ section, enter the key hash in the __Key Hash__ field.
1a44ca8 README clarifications
Steven Soneff authored
83
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
84 ![keyhash](http://sphotos.ak.fbcdn.net/hphotos-ak-snc4/hs992.snc4/76543_172095306140879_109700069047070_612908_7263236_n.jpg)
1a44ca8 README clarifications
Steven Soneff authored
85
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
86 * Insert a call to the authorizeCallback() method at the top of your Activity's onActivityResult() function. (If onActivityResult doesn't already exist, then create it)
1a44ca8 README clarifications
Steven Soneff authored
87
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
88 @Override
89 public void onActivityResult(int requestCode, int resultCode, Intent data) {
90 super.onActivityResult(requestCode, resultCode, data);
91 facebook.authorizeCallback(requestCode, resultCode, data);
92 // ... anything else your app does onActivityResult ...
93 }
1a44ca8 README clarifications
Steven Soneff authored
94
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
95 Testing
96 -------
97
98 Here are some tips to help test your application:
99
100 * You will need to have the Facebook application in your test environment. The SDK includes a developer release of the Facebook application that can be side-loaded for testing purposes. On an actual device, you can just download the latest version of the app from the Android Market, but on the emulator you will have to install it yourself:
101
102 adb install FBAndroid.apk
2cd0181 First draft of README file.
Luke Shepard authored
103
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
104 * Use a signed build. You can sign with a debug key, but make sure that the key you used to sign matches the __Key Hash__ field in the Facebook developer settings.
2cd0181 First draft of README file.
Luke Shepard authored
105
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
106 * Make sure to test both with and without the Facebook application. The SDK will fall back to a Webview if the Facebook app is not installed.
fc315c5 Updates to README
Steven Soneff authored
107
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
108 * You can use this [guide to developing on a device](http://developer.android.com/guide/developing/device.html).
fc315c5 Updates to README
Steven Soneff authored
109
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
110 Usage
111 =====
fc315c5 Updates to README
Steven Soneff authored
112
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
113 Begin by instantiating the Facebook object:
fc315c5 Updates to README
Steven Soneff authored
114
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
115 facebook = new Facebook(applicationId);
2cd0181 First draft of README file.
Luke Shepard authored
116
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
117 The Facebook object lets you do three major things:
118
119 * __Authentication and Authorization__: prompt users to log in to facebook and grant permissions to your application.
120 * __Making API Calls__: fetch user profile data (such as name and profile pic), as well as info about a user's friends.
c1ba90f Updates to README for platform dialogs.
Jim Brusstar authored
121 * __Display a dialog__: interact with user via a WebView. You primarily use this to publish to a user's feed without requiring upfront permissions.
fc315c5 Updates to README
Steven Soneff authored
122
b83307e Formatting tweaks.
Luke Shepard authored
123 Authentication and Authorization
fc315c5 Updates to README
Steven Soneff authored
124 --------------------------------
2cd0181 First draft of README file.
Luke Shepard authored
125
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
126 #### Making the authorize request
127
128 To login the current user, call the authorize() method. By default, your application can read the user's basic information, which includes their name, profile picture, list of friends, and other information that they have made public.
2cd0181 First draft of README file.
Luke Shepard authored
129
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
130 facebook.authorize(context, new AuthorizeListener());
2cd0181 First draft of README file.
Luke Shepard authored
131
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
132 Private user information is protected by [a set of granular permissions](http://developers.facebook.com/docs/authentication/permissions). If you want to access private information, use the authorize() method to request permission:
2cd0181 First draft of README file.
Luke Shepard authored
133
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
134 facebook.authorize(context,
135 String[] {"offline_access","user_photos"},
136 new AuthorizeListener())
2cd0181 First draft of README file.
Luke Shepard authored
137
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
138 You should use one of the buttons provided in the images/buttons/ directory to direct the user to login.
2cd0181 First draft of README file.
Luke Shepard authored
139
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
140 #### Login process
fc315c5 Updates to README
Steven Soneff authored
141
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
142 If the user has installed and is logged into the latest Facebook application on their device, then they will be directed to the Facebook app to grant permissions. If the user is not logged in, then they will need to do that first. If the Facebook application is not installed at all, then the Facebook Android SDK will gracefully fall back to a WebView-based flow that requires username/password.
2cd0181 First draft of README file.
Luke Shepard authored
143
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
144 #### Handle the authorize response
145
146 Your application handles the response with the __onComplete__ method of a __DialogListener__ object.
147
148 class AuthorizeListener implements DialogListener {
149 public void onComplete(Bundle values) {
150 // Handle a successful login
151 }
152 }
153
154 Check out the sample listeners for more details on the DialogListener interface.
155
156 ### Logging out
157
158 When the user wants to stop using Facebook integration with your application, you can call the logout method to clear all application state and invalidate the current OAuth token.
fc315c5 Updates to README
Steven Soneff authored
159
160 facebook.logout(context);
2cd0181 First draft of README file.
Luke Shepard authored
161
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
162 Making API calls
b83307e Formatting tweaks.
Luke Shepard authored
163 -----------------------
2cd0181 First draft of README file.
Luke Shepard authored
164
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
165 #### Graph API
166
167 The [Facebook Graph API](http://developers.facebook.com/docs/api) presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph (e.g., people, photos, events, and fan pages) and the connections between them (e.g., friend relationships, shared content, and photo tags).
2cd0181 First draft of README file.
Luke Shepard authored
168
169 You can access the Graph API by passing the Graph Path to the ''request'' method. For example, to access information about the logged in user, call
170
fc315c5 Updates to README
Steven Soneff authored
171 facebook.request("me"); // get information about the currently logged in user
172 facebook.request("platform/posts"); // get the posts made by the "platform" page
173 facebook.request("me/friends"); // get the logged-in user's friends
e9872fe Formatting tweaks.
Luke Shepard authored
174
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
175 Because the request call is synchronous (meaning it will block the calling thread), it should not be called from the main (UI) thread in Android. To make it non-blocking, you can make the request in a separate or background thread. For example:
e9872fe Formatting tweaks.
Luke Shepard authored
176
177 new Thread() {
178 @Override public void run() {
fc315c5 Updates to README
Steven Soneff authored
179 String resp = request("me");
e9872fe Formatting tweaks.
Luke Shepard authored
180 handleResponse(resp);
181 }
182 }.start();
2cd0181 First draft of README file.
Luke Shepard authored
183
fc315c5 Updates to README
Steven Soneff authored
184 See the AsyncFacebookRunner class and sample application for examples of making asynchronous requests.
185
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
186 #### Response format
187
188 The server response is a JSON string. The SDK provides a Util.parseJson() method to convert this to a JSONObject, whose fields and values can be inspected and accessed. The sample implementation checks for a variety of error conditions and raises JSON or Facebook exceptions if the content is invalid or includes an error generated by the server. Advanced applications may wish to provide their own parsing and error handling.
189
190 #### Old REST API
fc315c5 Updates to README
Steven Soneff authored
191
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
192 The [Old REST API](http://developers.facebook.com/docs/reference/rest/) is also supported. To access the older methods, pass in the named parameters and method name as a dictionary Bundle.
4281e7f Updates to configuration, README, cancel handling
Steven Soneff authored
193
fc315c5 Updates to README
Steven Soneff authored
194 Bundle parameters = new Bundle();
195 parameters.putString("method", "auth.expireSession");
196 String response = request(parameters);
197
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
198 See the comments on the __request__ method for more details.
2cd0181 First draft of README file.
Luke Shepard authored
199
7d21bf3 @bgold adding an anchor for dialogs
bgold authored
200 <a name="dialogs"/>
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
201 Display a Dialog
fc315c5 Updates to README
Steven Soneff authored
202 ----------------------
203
c1ba90f Updates to README for platform dialogs.
Jim Brusstar authored
204 This SDK provides a method for popping up a Facebook dialog for user interaction. This is useful if you want to publish to a user's feed without requesting a bunch of permissions first.
fc315c5 Updates to README
Steven Soneff authored
205
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
206 To invoke a dialog:
207
208 facebook.dialog(context,
c1ba90f Updates to README for platform dialogs.
Jim Brusstar authored
209 "feed",
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
210 new SampleDialogListener());
fc315c5 Updates to README
Steven Soneff authored
211
212
29c2b0a Formatting tweak.
Luke Shepard authored
213 Error Handling
214 --------------
2cd0181 First draft of README file.
Luke Shepard authored
215
fc315c5 Updates to README
Steven Soneff authored
216 For synchronous methods (request), errors are thrown by exception. For the asynchronous methods (dialog, authorize), errors are passed to the onException methods of the listener callback interface.
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
217
218 Debugging
219 ==========
220
221 Here's a few common errors and their solutions.
222
223 * __Build error: "missing gen files".__
224
225 This should go away when you rebuild the project. If you have trouble, try running __Clean...__ from the __Project__ menu.
226
227 * __Error: "invalid_key"__
228
e23764f @jimbru Clarifying the "invalid_key" debugging info.
jimbru authored
229 This error means that the Facebook server doesn't recognize your Android key hash. Make sure that you correctly generated and copy/pasted your key hash into the Facebook developer settings console (http://www.facebook.com/developers/apps.php), and make sure that your application has been signed with the same key you registered with Facebook.
a1fb45a Add support for single sign-on to Android SDK
Luke Shepard authored
230
231 * __Dialog won't load or shows a blank screen.__
232
233 This can be tricky to debug. If the logs don't give an indication of what's wrong, I suggest installing tcpdump on your device and getting a trace. Tutorial: http://www.vbsteven.be/blog/android-debugging-inspectin-network-traffic-with-tcpdump/
234
235 If you still can't tell what's going on, then file an issue and please include the HTTP trace.
236
237 * __I can't upload photos with photos.upload.__
238
239 Make sure the Bundle value for the photo parameter is a byte array.
Something went wrong with that request. Please try again.