most succinctly: Bamboo aims to meet all your Facebook needs as an iPhone application developer.
Bamboo (http://github.com/ryanscott/bamboo) is a new Facebook Graph library for use in iPhone development. Bamboo is a simple, lightweight, robust alternative to using the old Facebook Connect API, and a time-saving alternative to directly writing your own network code. The library is designed very similarly to Koala (http://github.com/arsduo/koala), a Ruby port of the Python library that Facebook published. Bamboo is more or less an objective-c port of the ruby port. The basic API structure is the same, and for the most part the design goals are the same.
This is as easy as it gets at integrating Facebook into an iPhone application. Using Bamboo will save you hours, probably days, of development time.
To understand the GraphAPI concepts from the perspective of a third-party library, read the Koala documentation and walkthrough.
http://wiki.github.com/arsduo/koala/
Alex also wrote a fabulous, very in-depth tutorial on how to use Koala, and everything he says applies to Bamboo, even the method names are the same, for your convenience.
http://blog.twoalex.com/2010/05/03/introducing-koala-a-new-gem-for-facebooks-new-graph-api/
Sample usage:
[[FacebookProxy instance] loginAndAuthorizeWithTarget:self callback:@selector(finishedAuthorizing)];
GraphAPI* graph = [[FacebookProxy instance] newGraph];
GraphObject* me = [graph getObject:@"me"];
NSString* myName = me.name;
UIImage* myProfileImage = [me largePicture];
NSArray* thingsILike = [graph getConnections:@"likes" forObject:me.objectID];
// update status message to my feed/wall
NSDictionary* args = [NSDictionary dictionaryWithObjectsAndKeys:@"Hello World, from bamboo!", @"message", nil];
[self._graph putToObject:me.objectID connectionType:@"feed" args:args];
// add a like connection from me to you
[self._graph likeObject:@"<you>"]
- Install bamboo and dependencies from your project directory:
- Open your project, make a group called "Libraries," and add all source files from bamboo and facebook-iphone-sdk
- Define the following 4 global variables:
- Include "GraphAPI.h" write the following 2-ish lines of code in your klass.m:
- Make calls to the Facebook graph using your GraphAPI object.
git clone http://github.com/ryanscott/bamboo.git
git clone http://github.com/facebook/facebook-iphone-sdk.gitNSString* const kFBAPIKey = @"";
NSString* const kFBAppSecret = @"";
NSString* const kFBClientID = @"";
NSString* const kFBRedirectURI = @"";If you need help on any of those, get help at http://developers.facebook.com/docs/api#authorization or http://oauth.twoalex.com/
See Constants.m in samples/testgraph for example values.
// klass.m
[[FacebookProxy instance] loginAndAuthorizeWithTarget:self callback:@selector(finishedAuthorizing)];
-(void)finishedAuthorizing
{
self._graph = [[FacebookProxy instance] newGraph];
}
// klass.h
GraphAPI* _graph;
@property (nonatomic, retain) GraphAPI* _graph;More documentation and more extensive sample app forthcoming.
Check the /samples/ directory, which includes code for an app named testgraph. I use this app as an area to develop and test new functionality.
The main integration point is FacebookProxy, which handles all of the messiness of authorization. The following 4 variables need to be defined in your app. See Constants.m in testgraph for example values.
// Facebook API
// all of these values need to be set in the client application
extern NSString* const kFBAPIKey;
extern NSString* const kFBAppSecret;
extern NSString* const kFBClientID;
extern NSString* const kFBRedirectURI;Generally speaking, your app needs to get an access_token to use graph.facebook.api. Once you have a token, you can pretty much keep using it ad infinitum as far as I can tell. The FacebookProxy class handles all the login & token grabbing piping, right now using a oAuth sandbox setup by Alex for Koala. That will need to be handled by the lib client on an app by app basis.
Bamboo relies on the official Facebook Connect iPhone SDK for login. Additionally, I use json-framework for parsing the responses from Facebook, but rather than have an external link to the repo I have included the files directly in the bamboo project, so you don't have to do anything. Both of these are not 100% necessary in theory, so if you want a version of bamboo with no dependencies whatsoever it can easily be done...it just won't be as usable.
http://github.com/facebook/facebook-iphone-sdk
http://github.com/stig/json-framework
No asynchronous network access
Being a really early stage library, Bamboo will most certainly need work to support all the various app environments. I have designed the base library to meet the most common needs that I have imagined, and as the user base grows, I expect the API to grow as well. If you are using the library, or want to use it, and your needs are only partially met, please let me know so I can grow the library design to meet your needs.
If you are interested in contributing to Bamboo, by all means please contact me (ryan (at) ryanstubblefield [dot] net). I welcome anyone who wants to help, and prefer to keep forks at a minimum.
The best, most direct way to reach me is via email (ryan (at) ryanstubblefield [dot] net).
You can find out more about me at http://www.ryanstubblefield.net/