Description

The TweetPhoto Objective-C library is a set of drop in classes designed to allow developers to get up and running quickly with the TweetPhoto Photo Sharing API.

This library includes every feature you'll need to manage the entire photo sharing experience within your application - from uploading photos, commenting, favoritng, and voting to social feeds, user feeds, and everything in between.

To help contribute to this Objective-C library and open source project please feel free to contact us.

Before You Start

You should be familiar with the TweetPhoto REST API, found here.

You should also sign up and obtain a TweetPhoto API Key, here.

Using the Library

In order to use the TweetPhoto Objective-C library, you will need to download the TPAPITest project, and drag the Group Named TweetPhoto into your project (make sure you copy the source to your target project).

Create a TweetPhoto Instance

To use the TweetPhoto API class, you will need to create a TweetPhoto instance like the following:

``` import "TweetPhoto.h"

TweetPhoto * tweetPhoto = [[TweetPhoto alloc] initWithSetup:@"username" identitySecret:@"password" apiKey:@"yourapikeyhere" serviceName:@"servicename" isoAuth:YES|NO]; ```

Where:

username is either your username from the authenticating service if you are using Basic Authentication, or the Access Token Key from the authenticating service if you are using oAuth authentication.

password is either your password from the authenticating service if you are using Basic Authentication, or the Access Token Secret from the authenticating service if you are using oAuth authentication.

yourapikey is the TweetPhoto API Key, obtainable here: [url:http://admin.tweetphoto.com/Api.aspx]

servicename is the service that you will be using to authenticate against. Valid services are TweetPhoto, Twitter, and Foursquare.

isoAuth determines how your credentials will be presented to TweetPhoto (i.e., are you using oAuth credentials to authenticate). If the value entered here is NO, then Basic Authentication will be used and you will supply a valid username and password for the authenticating service. If the value entered here is YES, then the TweetPhoto API will expect a valid Access Token Key and Access Token Secret to be set (see username and password above). In order to make OAuth requests, please contact TweetPhoto, as we require you to share your OAuth ConsumerKey and ConsumerSecret, so that the TweetPhoto API may make requests on your behalf. This also allows you to pass OAuth Token/Secret pair without compromising them since they are useless without the ConsumerKey and ConsumerSecret.

Additional Notes on Authentication

The Twitter Service supports both Basic Authentication and oAuth authentication. TweetPhoto recommends using oAuth authentication, since Twitter will deprecate Basic Authentication support in the future.

Foursquare supports only oAuth Authentication.

You can find everything you ever wanted to know about oAuth here.

Before using any provider for oAuth authentication, you will need to register your application with the provider to receiver a Consumer Key and a Consumer Secret. Both of these items will need to be used to prepare your oAuth calls to the provider (and will incidentally be needed by the TweetPhoto API in order to make calls on your behalf).

In order to use oAuth credentialing, you will need to obtain an Access Token Key and Access Token Secret pair from the provider which you wish to authenticate through. In general, the steps are:

Request an unauthorized token

Authenticate to the Provider using the unauthorized token

Receive an access token key / access token secret to use in subsequent TweetPhoto API calls.

A very good oAuth consumer library for the iPhone is OAuthConsumer, available here: [url:http://github.com/jdg/oauthconsumer].

The following code demonstrates OAuthConsumer-based code (a) requesting an authorization token, (b) calling the provider to authenticate using the authorization token, and (c) taking the returned access token key and access token secret passed back by the provider once access is granted to be stored and used for subsequent calls to TweetPhoto:

``` // Get oAuth Access Token -(void)getoAuthAccessToken {

OAConsumer *consumer = [[[OAConsumer alloc] initWithKey:self.consumerKey secret:self.consumerSecret] autorelease]; NSURL *url = [self.serviceName isEqualToString:@"Twitter"] ? [NSURL URLWithString:@"http://twitter.com/oauth/access_token"] : [NSURL URLWithString:@"http://foursquare.com/oauth/access_token"];

if (self.requestToken==nil) {
    if ([self.serviceName isEqualToString:@"Twitter"]) {
        self.requestToken = [[OAToken alloc] initWithKey:[[NSUserDefaults standardUserDefaults] stringForKey:@"requestTokenKey"] secret:[[NSUserDefaults standardUserDefaults] stringForKey:@"requestTokenSecret"] verifier:[[NSUserDefaults standardUserDefaults] stringForKey:@"accessTokenVerifier"]];
        }
    if ([self.serviceName isEqualToString:@"Foursquare"]) {
        self.requestToken = [[OAToken alloc] initWithKey:[[NSUserDefaults standardUserDefaults] stringForKey:@"requestTokenKey"] secret:[[NSUserDefaults standardUserDefaults] stringForKey:@"requestTokenSecret"] verifier:[[NSUserDefaults standardUserDefaults] stringForKey:@"accessTokenVerifier"]];
        }
    }

    OAMutableURLRequest *request = [[OAMutableURLRequest alloc] initWithURL:url consumer:consumer token:self.requestToken realm:nil signatureProvider:nil]; // use the default method, HMAC-SHA1

    OADataFetcher *fetcher       = [[[OADataFetcher alloc] init] autorelease];

[request setHTTPMethod:@"GET"];

[fetcher fetchDataWithRequest:request delegate:self didFinishSelector:@selector(requestAccessTokenTicket:didFinishWithData:) didFailSelector:@selector(requestAccessTokenTicket:didFailWithError:)];

}

// Request Access Token Failed - (void)requestAccessTokenTicket:(OAServiceTicket *)ticket didFailWithError:(NSError )error { TweetPhotoAppDelegate myApp = (TweetPhotoAppDelegate*)[[UIApplication sharedApplication] delegate];

[self decodeNSData:[ticket.request HTTPBody] description:@"HTTP Body"];

if ([self.serviceName isEqualToString:@"Twitter"]) {
    UIAlertView* myAlert = [[UIAlertView alloc] initWithTitle:@"TweetPhoto - Twitter Authentication" message:[NSString stringWithFormat:@"Request Access Token Failed: %@", @"Please re-enter your PIN and try again."] delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
    [myAlert show];
    [myAlert release];    
    [myApp flipPINToFront];
    }

if ([self.serviceName isEqualToString:@"Foursquare"]) {
    UIAlertView* myAlert = [[UIAlertView alloc] initWithTitle:@"TweetPhoto - Foursquare Authentication" message:[NSString stringWithFormat:@"Request Access Token Failed: %@", error] delegate:nil cancelButtonTitle:@"OK" otherButtonTitles:nil];
    [myAlert show];
    [myAlert release];    
    [myApp flipLoginToFront];
    }

}

// Successfully received an access token - (void)requestAccessTokenTicket:(OAServiceTicket *)ticket didFinishWithData:(NSData *)data {

if (ticket.didSucceed) {
    NSString *responseBody = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

    // Save our access token info locally
    self.accessToken      = [[OAToken alloc] initWithHTTPResponseBody:responseBody];
    [responseBody release];

    NSUserDefaults *standardUserDefaults = (NSUserDefaults *)[NSUserDefaults standardUserDefaults];
    [standardUserDefaults setObject:self.accessToken.key        forKey:@"accessTokenKey"];
    [standardUserDefaults setObject:self.accessToken.secret     forKey:@"accessTokenSecret"];

    self.identityToken  = self.accessToken.key;
    self.identitySecret = self.accessToken.secret;

    self.accessToken.verifier = [[NSUserDefaults standardUserDefaults] stringForKey:@"accessTokenVerifier"];

    [self signIn];
    }

}

// Request oAuth Token -(void)getoAuthToken {

OAConsumer *consumer         = [[[OAConsumer alloc] initWithKey:self.consumerKey secret:self.consumerSecret] autorelease];

// Dependent upon serviceName==@"Twitter" or @"Foursquare"
NSURL *url                   = [self.serviceName isEqualToString:@"Twitter"] ? [NSURL URLWithString:@"http://twitter.com/oauth/request_token"] : [NSURL URLWithString:@"http://foursquare.com/oauth/request_token"];

OAMutableURLRequest *request = [[OAMutableURLRequest alloc] initWithURL:url consumer:consumer token:nil realm:nil signatureProvider:nil]; // use the default method, HMAC-SHA1

OADataFetcher *fetcher       = [[[OADataFetcher alloc] init] autorelease];

[fetcher fetchDataWithRequest:request delegate:self didFinishSelector:@selector(requestTokenTicket:didFinishWithData:) didFailSelector:@selector(requestTokenTicket:didFailWithError:)];

}

// Successfully received a request token - (void)requestTokenTicket:(OAServiceTicket *)ticket didFinishWithData:(NSData )data { if (ticket.didSucceed) { TweetPhotoAppDelegate myApp = (TweetPhotoAppDelegate*)[[UIApplication sharedApplication] delegate]; NSString *responseBody = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];

    // Save our request token
    self.requestToken      = [[OAToken alloc] initWithHTTPResponseBody:responseBody];

    NSUserDefaults *standardUserDefaults = (NSUserDefaults *)[NSUserDefaults standardUserDefaults];

    [standardUserDefaults setObject:self.requestToken.key    forKey:@"requestTokenKey"];
    [standardUserDefaults setObject:self.requestToken.secret forKey:@"requestTokenSecret"];

    [responseBody release];

    // Handle Twitter
    if ([self.serviceName isEqualToString:@"Twitter"]) {
                    // Open a UIWebView to call Twitter for authentication
        [myApp flipWebToFront:[NSString stringWithFormat:@"http://twitter.com/oauth/authorize?oauth_token=%@",self.requestToken.key]];
        }

    // Handle Foursquare
    if ([self.serviceName isEqualToString:@"Foursquare"]) {
                    // Open a UIWebView to call Foursquare for authentication
        [myApp flipWebToFront:[NSString stringWithFormat:@"http://playfoursquare.com/oauth/authorize?oauth_token=%@",self.requestToken.key]];
        }
    }

}

// Request Token Failed - (void)requestTokenTicket:(OAServiceTicket *)ticket didFailWithError:(NSError *)error { NSLog(@"Request Token Failed: %@", error); }

```

Sign In

The first operation that you should perform once you have created a TweetPhoto instance is to sign in. This will determine whether TweetPhoto recognizes your credentials or not.

// Sign In Profile * profile = [self.tweetPhoto signIn]; if (profile) { NSLog(@"Sign In: %@", profile); [profile release]; } else { NSLog(@"Login Error. Status Code: %d", tweetPhoto.statusCode); }

Upload a Photo

Uploading a photo to TweetPhoto is extremely straightforward:

TweetPhotoResponse * tr = [self.tweetPhoto photoUpload:UIImageJPEGRepresentation([UIImage imageNamed:@"16.png"], 0.5) comment:@"Da Mona Lisa" tags:@"sample, test, standalone api, and such..." latitude:24.559614 longitude:-81.783085]; NSLog(@"Photo Upload: %@", tr); [tr release];