Using Bump’s New API To Exchange Data Between Phones

Bump, the Y Combinator funded company that got a lot of attention last year as the Billionth App, has released an API that lets devs use Bump’s bump-to-exchange scheme for swapping data phone-to-phone in their own apps.

The API is free to use unless you are generating revenue as a direct result of a bump, have more than 10,000,000 bumps/month or more than 2,500 simultaneous users.

Integrating the API looks straightforward and uses the protocol/delegate pattern familiar to iPhone devs. Have a look at this tutorial for details.

 

API Tutorial

This tutorial provides a step-by-step howto for integrating the Bump API with an iPhone app.

Source & Installation

Let's first download a sample Xcode project that will use the Bump API: BumpFour. Next, download the Bump API. Now, open the BumpFour Xcode project that you just downloaded.

Locate the API-distro_* folder (that you downloaded), drag the file Bump.h and drop it onto the BumpFour project Classes group. A dialog will appear -- make sure "Copy items" is checked before clicking "Add".

Next, drag the Bump_Resources folder and drop it onto the BumpFour project Resources group. A dialog will appear -- make sure "Copy items" is checked before clicking "Add".

Then, drag libBump.a and drop it onto the BumpFour project Frameworks group. A dialog will appear -- make sure "Copy items" is checked before clicking "Add".

If you're integrating the Bump API with your Xcode project, make sure your project includes the CoreLocation, AudioToolbox, UIKit, Foundation, CoreGraphics frameworks. The BumpFour sample project already included these frameworks.

When you have added all the required Bump API assets, the Groups & Files will look similar to these:

Compile

At the time you register, you receive an API key. You need to insert your API key in GameBumpConnector.m here:

Press "Build and Go". If you've added (installed) everything correctly and you have a valid developer key, BumpFour should run on your simulator. Press "PLAY FRIEND". You should see this:

[Note: A demo warning message will show when you are not using a production key. To upgrade your API developer key to a production key, go here.]

Using the Bump API: Bump and exchange data

There are a few calls to make to integrate Bump with your project. These are the minimum calls you must make in order to bump and exchange data.

Let's take a look at the sample project BumpFour where the calls are made.

1. Allocate a Bump object
   bumpObject = [[Bump alloc] init]; // Bump *bumpObject;
2. Set a delegate
   [bumpObject setDelegate:self];
3. Use your API key
   [bumpObject configAPIKey:@"YOUR_API_KEY"];
4. Connect with Bump's server. You must only call this after the previous three calls.
   [bumpObject connect];
   

   BumpFour calls this when user presses a button to "Play Friend". That's one way to invoke the Bump API popup. Another way might be, for example, if your app allows your users to bump a photo, when the user selects a photo from your photo picker, you can call connect. That will immediately bring up the Bump API popup, users bump, and photo is exchanged.

5. Implement the required BumpDelegate methods
   - (void) bumpDidConnect; - (void) bumpDidDisconnect:(BumpDisconnectReason)reason; - (void) bumpConnectFailed:(BumpConnectFailedReason)reason; - (void) bumpDataReceived:(NSData *)chunk;
6. Send and receive data
   [bumpObject send:moveChunk]; // NSData *moveChunk = [NSKeyedArchiver archivedDataWithRootObject:moveDict];
7. Disconnect from Bump's server
   [bumpObject disconnect];

In addition to the minimum calls above, the following are useful.

1. Send a message to the Bump feed
   [bumpObject configHistoryMessage:@"%1 just started a BumpFour match with %2!"];
2. Configure a message on the Bump API popup:
   [bumpObject configActionMessage:@"Bump with another BumpFour player to start game."];

Using the Bump API: Bump and share your app

The Bump API also has a "tell-a-friend" feature. To implement that in your app, send the connectToShareThisApp message to your Bump object. In addition, you instruct your users to bump your app into the Bump App via the configActionMessage:, doing so will take the receiver (the Bump App) to the iTunes page for your app. Let's take a look at a view controller whose sole function is to share app (we won't reference BumpFour for this example).

ShareAppViewController.h #import <UIKit/UIKit.h> #import "Bump.h" @interface ShareAppViewController : UIViewController { Bump *_bumpObject; } @end ShareAppViewController.m #import "ShareAppViewController.h" @implementation ShareAppViewController -(id)init { self = [super init]; _bumpObject = [[Bump alloc] init]; return self; } - (void)loadView { [_bumpObject configAPIKey:@"INSERT_YOUR_API_KEY_HERE"]; [_bumpObject configActionMessage:@"Share this app by bumping with a user of the Bump App"]; } -(void)viewWillAppear:(BOOL)animated { [super viewWillAppear:animated]; [_bumpObject connectToShareThisApp]; } - (void)dealloc { [_bumpObject release]; [super dealloc]; } @end

 

http://www.mobileorchard.com/

http://bu.mp/apitutorial.html