iOS Twitter framework

Updated on Fri, 2012-04-13 08:19 1. 2. 3. 4. 5. 6. 7. 8. Overview Go to the source What can I do with the framework? Single Sign-On Distribution Instant Personalization Accessing the Twitter API Have questions?

iOS Twitter framework

Overview
With iOS5, Apple has introduced a new framework that enables your iOS applications to leverage the power of Twitter. The framework removes many of the common obstacles encountered when accessing Twitters API, including authentication and Tweet composition, and allows developers to focus on more meaningful levels of integration that enrich their application experiences.

Go to the source
With the Twitter framework, as with any iOS-related topic, the Apple Developer Site should be considered the ultimate source of development references, guides and code for developers. It is also where you should start if you encounter generic iOS issues that you cannot resolve on your own.

WWDC information
The Twitter integration was announced at the 2011 WWDC Keynote (announcement is at 49:03). Additionally, Developer Session 124, Twitter Integration, was held to introduce to framework to developers. You should at least review the WWDC Session 124 video before proceeding with your integration.

Documentation, example and forums

Apples Developer Library includes many guides and references that can assist you if you need help. Before attempting to build an iOS5 Twitter integration, it is highly recommended that you review the following: The Twitter Framework Reference documents the classes in the framework. The Account Framework Reference documents the Account framework, which is used in conjunction with Twitter.framework. The ofcial Twitter framework example from Apple is available for download.

Finally, the Apple Developer Forums are a great place to have your questions answered by Apple employees and developers in the iOS ecosystem.

What can I do with the framework?

As a mobile application developer, there are 3 key facets of the Twitter framework that you can leverage in your applications: 1. 2. 3. Single Sign-On Distribution Instant Personalization

In addition to these main integration points, the framework also makes it incredibly easy to integrate your application with any of Twitter's APIs by handling common obstacles, such as authentication, for you so you can focus on building an amazing experience for your users. To help developers understand the integration potential for their own products, we have highlighted 10 showcase applications that leverage the framework at http://ios.twitter.com. As always, be aware that if your application accesses Twitter, it is bound to the Twitter Terms of Service.

iOS Twitter framework

Single Sign-On
With iOS5, a users Twitter credentials are stored in a central account store, ACAccountStore, that is accessible from applications on the device. The rst time that an application attempts to access a user's Twitter account, a user is presented a dialog requesting access to his or her Twitter account:

Figure 1: The Account Access Prompt Once a user has granted permission to an application, the user is not prompted again. The experience is very similar to that of an application that leverages Location Services in that once a user has either granted or rejected access for the application, the prompt is not shown again. A user may manually add his credentials, or an application can provide pre-veried OAuth tokens and secrets to add the users Twitter account to the device. The latter scenario is useful for applications that have already authenticated users, either on the device or on a server-side integration. The process for migrating existing tokens to core accounts is explained at Migrating tokens to system accounts.

Reverse Authentication
If your application requires signed authentication tokens from the device for a server-side integration, you can do so with a special process called Reverse Auth. More information about Reverse Auth is described at Using Reverse Auth. Once a users Twitter account has been stored on the device, any application on the device can request access from the user to make authenticated requests on his or her behalf.

Distribution
The Twitter framework contains a standard, easy-to-invoke dialog for composing Tweets, TWTweetComposeViewController, that is also commonly referred to as the Tweet Sheet. With this dialog, you can set initial text, images, and links and present the composition to the user in a modal window. The user has the ability to edit the content of the Tweet before sending, including content that you set before presenting the view. The Tweet Sheet contains built-in functionality that enriches the users experience: The user can add his location and select from multiple accounts, and the Tweet Sheet will also auto-complete user names for the user while they are typing free-form text.

iOS Twitter framework

Figure 2: The Tweet Sheet

iOS Twitter framework

Instant Personalization
Mobile devices provide valuable signals that can be used to personalize and enrich a users experience; for example, a device's GPS, if available programmatically, provides details on where a user is geographically that the developer can use to display localized information. Now with the Twitter framework, you can personalize your applications experience for a user based on the users interest graph in addition to these other signals to create unique, targeted mobile apps. Consider the scenario where a new user downloads and opens your application for the rst time. At this point, you know very little about the user, but if the user has a Twitter account congured on the device, you can quickly--and easily--surface relevant content to the user based on his Twitter timeline. This instant personalization is key to building a relationship with your user, and will increase the likelihood that the user returns to your application.

Accessing the Twitter API

The Twitter framework provides TWRequest which encapsulates requests to Twitters REST API and handles user authentication seamlessly. With TWRequest, you can cleanly separate your requests to Twitter and process the results using block-based handlers. When you need to make authenticated calls on a user's behalf, you do so by attaching a local Twitter account instance, instead of manually performing an OAuth signing operation. For more information, TWRequest is documented with examples at API requests with TWRequest.

What about Direct Messages?

The Twitter framework cannot read or delete Direct Messages but it can send them. If your application requires the ability to read or delete Direct Messages, you must follow the traditional OAuth web ow to obtain the users permission. You should then use the returned access token and secret for future calls that require DM read permission.

Have questions?
If you have questions that you would like to ask the developer community, as well as Twitter's developer advocates, please post them in the Mobile Development Discussion Forum.

iOS Twitter framework

Adding the Twitter Framework

Updated on Mon, 2011-10-31 13:11

Overview
Starting with iOS5, Apple has added a Twitter Framework to iOS. With this Framework, you can easily leverage the power of Twitter for single sign-on, content personalization and content sharing. This document walks you through the simple process of adding Twitter to a new or existing project.

Apple's Documentation
For general iOS and XCode documentation, please refer to Apple's Developer Site. Apple's Developer Library contains, among many other outstanding articles, the following relevant topics: XCode 4 User Guide Adding an Existing Framework to a Project Twitter Framework Reference

Adding the Framework to your Application

To begin, open your application in XCode.

iOS Twitter framework

In the project explorer, select the target that you would like to link against Twitter.framework. In this example, the target name is TwitterExample.

Next, nd the "Linked Frameworks and Libraries" module. You may have to expand the entry. Click the "+" sign to add a new Framework.

iOS Twitter framework

In the search eld, enter "Twitter" and select the Twitter.Framework entry and click the "Add" button. Note that you may have to expand the "iOS 5.0" entry to see the framework. You have now successfully added the framework to your project. If you encounter any problems, please raise a question in the Twitter API Discussion Forums.

iOS Twitter framework

API requests with TWRequest

Updated on Mon, 2012-06-04 14:19

Overview
TWRequest is a class in the Twitter framework for iOS5 that encapsulates HTTP requests to Twitters REST API. The object can also handle authenticating users for the caller.

Recommended Reading
The following articles on Apple's Developer Site will help you as you work with TWRequest: TWRequest Class Reference ACAccount Class Reference NSJSONSerialization Class Reference A Short Practical Guide to Blocks

How do I perform requests with TWRequest?

With TWRequest, you can perform both unauthenticated requests and authenticated requests to the Twitter REST API. The real power lies in the seamless way it handles authenticated requests, but to start, we will demonstrate how you can use it to generate unauthenticated requests to the API. Unauthenticated Requests For this example, consider a situation where you would like to retrieve the public timeline for a Twitter user with GET statuses/user_timeline. The one required parameter that we must pass to the endpoint is screen_name, but for illustration purposes, we will also pass other options to the endpoint: count, to limit the returned results, include_entities to see the entities for each object, and include_rts to include the users retweets in the responses.

screen_name - theSeanCook count - 5 include_entities - 1 include_rts - 1

The equivalent HTTP request would be of this format: GET http://api.twitter.com/1/statuses/user_timeline.json? screen_name=theSeanCook&count=5&include_entities=1&include_rts=1 To use TWRequest to make this unauthenticated request, we would do the following:
iOS Twitter framework

Source Code Notes:

This example utilizes Automatic Reference Counting (ARC). Extraneous line breaks are added for clarity
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. // First, we create a dictionary to hold our request parameters NSMutableDictionary *params = [[NSMutableDictionary alloc] init]; [params setObject:@"theSeanCook" forKey:@"screen_name"]; [params setObject:@"5" forKey:@"count"]; [params setObject:@"1" forKey:@"include_entities"]; [params setObject:@"1" forKey:@"include_rts"]; // Next, we create an URL that points to the target endpoint NSURL *url = [NSURL URLWithString:@"http://api.twitter.com/1/statuses/user_timeline.json"]; // Now we can create our request. Note that we are performing a GET request. TWRequest *request = [[TWRequest alloc] initWithURL:url parameters:params requestMethod:TWRequestMethodGET]; // Perform our request [request performRequestWithHandler: ^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) { if (responseData) { // Use the NSJSONSerialization class to parse the returned JSON NSError *jsonError; NSArray *timeline = [NSJSONSerialization JSONObjectWithData:responseData options:NSJSONReadingMutableLeaves error:&jsonError]; if (timeline) { // We have an object that we can parse NSLog(@"%@", timeline); } else { // Inspect the contents of jsonError NSLog(@"%@", jsonError); } } }];

Authenticated Requests
The real power of TWRequest is its handling of user authentication. In this example, we will rst query the accounts that the user has stored on the device, then for the rst account returned we retrieve the user's home timeline using GET statuses/home_timeline, which requires authentication. We will once again pass a parameter to the endpoint, include_rts, to illustrate how easy it is to do so with TWRequest.

include_rts - 1

The equivalent HTTP request would be an OAuth-signed request of this format:

iOS Twitter framework

GET http://api.twitter.com/1/statuses/home_timeline.json?include_rts=1 To use TWRequest to make this authenticated request, we would do the following: Source Code Notes: This example utilizes Automatic Reference Counting (ARC). Extraneous line breaks are added for clarity
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. // First, we need to obtain the account instance for the user's Twitter account ACAccountStore *store = [[ACAccountStore alloc] init]; ACAccountType *twitterAccountType = [store accountTypeWithAccountTypeIdentifier:ACAccountTypeIdentifierTwitter]; // Request permission from the user to access the available Twitter accounts [store requestAccessToAccountsWithType:twitterAccountType withCompletionHandler:^(BOOL granted, NSError *error) { if (!granted) { // The user rejected your request NSLog(@"User rejected access to the account."); } else { // Grab the available accounts NSArray *twitterAccounts = [store accountsWithAccountType:twitterAccountType]; if ([twitterAccounts count] > 0) { // Use the first account for simplicity ACAccount *account = [twitterAccounts objectAtIndex:0]; // Now make an authenticated request to our endpoint NSMutableDictionary *params = [[NSMutableDictionary alloc] init]; [params setObject:@"1" forKey:@"include_entities"]; // The endpoint that we wish to call NSURL *url = [NSURL URLWithString:@"http://api.twitter.com/1/statuses/home_timeline.json"]; // Build the request with our parameter TWRequest *request = [[TWRequest alloc] initWithURL:url parameters:params requestMethod:TWRequestMethodGET]; // Attach the account object to this request [request setAccount:account]; [request performRequestWithHandler: ^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) { if (!responseData) { // inspect the contents of error NSLog(@"%@", error); } else { NSError *jsonError; NSArray *timeline = [NSJSONSerialization JSONObjectWithData:responseData options:NSJSONReadingMutableLeaves error:&jsonError]; if (timeline) { // at this point, we have an object that we can parse NSLog(@"%@", timeline); iOS Twitter framework

56. } 57. else { 58. // inspect the contents of jsonError 59. NSLog(@"%@", jsonError); 60. } 61. } 62. }]; 63. 64. } // if ([twitterAccounts count] > 0) 65. } // if (granted) 66. }];

iOS Twitter framework

Posting images using TWRequest

Updated on Wed, 2012-02-01 17:53

Overview
The Twitter framework's TWRequest encapsulates calls to the Twitter API, including signing the request on behalf of the user. With Twitter's photo hosting service, and its API endpoint POST statuses/update_with_media, it is possible to post a Tweet and a status simultaneously via a TWRequest.

Code Example
Before posting a Tweet with an attached image, you should check GET help/conguration to check the characters_reserved_per_media and max_media_per_upload values. The former tells you how many characters out of 140 you should reserve for the URL of the posted image, while the latter tells you the number of images that you can attach to the Tweet. Once you know the current Twitter conguration, you can post the Tweet. You use the TWRequest just as you would for any Twitter API call, but make sure that both the data and the status' text as "multipart/form-data." Notes:
4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28.

This example utilizes Automatic Reference Counting (ARC). Extraneous line breaks are added for clarity
- (void)performTWRequestUpload { NSURL *url = [NSURL URLWithString: @"https://upload.twitter.com/1/statuses/update_with_media.json"]; // Create a POST request for the target endpoint TWRequest *request = [[TWRequest alloc] initWithURL:url parameters:nil requestMethod:TWRequestMethodPOST]; // self.accounts is an array of all available accounts; // we use the first one for simplicity [request setAccount:[self.accounts objectAtIndex:0]]; // The "larry.png" is an image that we have locally UIImage *image = [UIImage imageNamed:@"larry.png"]; // Obtain NSData from the UIImage NSData *imageData = UIImagePNGRepresentation(image); // Add the data of the image with the // correct parameter name, "media[]" [request addMultiPartData:imageData iOS Twitter framework

29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56.

withName:@"media[]" type:@"multipart/form-data"]; // NB: Our status must be passed as part of the multipart form data NSString *status = @"just setting up my twttr #iOS5"; // Add the data of the status as parameter "status" [request addMultiPartData:[status dataUsingEncoding:NSUTF8StringEncoding] withName:@"status" type:@"multipart/form-data"]; // Perform the request. // Note that -[performRequestWithHandler] may be called on any thread, // so you should explicitly dispatch any UI operations to the main thread [request performRequestWithHandler: ^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) { NSDictionary *dict = (NSDictionary *)[NSJSONSerialization JSONObjectWithData:responseData options:0 error:nil]; // Log the result NSLog(@"%@", dict); dispatch_async(dispatch_get_main_queue(), ^{ // perform an action that updates the UI... }); }]; }

iOS Twitter framework

Using the Tweet Sheet

Updated on Mon, 2011-11-07 11:12

Overview
The Twitter framework includes a powerful all-in-one class for composing Tweets called TWTweetComposeViewController, also known as the "Tweet Sheet". The Tweet Sheet provides multiple mechanisms that enhance the user experience that have previously required developer support to implement: The UI of the sheet is handled for you You can set the initial text of the Tweet, attach images, and attach URLs The Tweet Sheet handles multiple accounts seamlessly The controller autocompletes usernames as the user composes the Tweet It handles counting characters to ensure the 140 character limit

Recommended Reading
The following items are provided by Apple, and should be consulted rst if you have any questions about using TWTweetComposeViewController. As always, you should consider the Apple documentation the denitive source of information for iOS. TWTweetComposeViewController reference The ofcial sample application WWDC 2011 Session 124, "Twitter Integration"

How do I use the Tweet Sheet in my application?

Invoking the Tweet Sheet in your application is quite simple. First, you should ensure that you have added the Twitter.framework to your project as described in Adding the Twitter Framework . Once you have added the framework to your project, using the Tweet Sheet is as simple as: 1. 2. 3. 4. Initialize a Tweet Sheet Congure the initial text, images, and URLs that you would like to set (if any) Congure the result handler Display the Tweet Sheet using -[presentViewController:animated:completion:] (Note: as of iOS5, this is the preferred method instead of [presentModalViewController:animated])

Code Example
Below is an example of the above steps. Note that the methods for setting initial content respond with Boolean values; this allows you, the developer, to not have to worry about the current count of characters in the body of the Tweet that you are initializing. If the method returns YES, there was enough room to add the content. If the method returns NO, the content you attempted to add would
iOS Twitter framework

result in a Tweet longer than 140 characters. The logic for character counting also takes into effect the current number of characters required for t.co URL wrapping.

Source Code Notes:

This example utilizes Automatic Reference Counting (ARC). Extraneous line breaks are added for clarity
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. - (void)showTweetSheet { // Create an instance of the Tweet Sheet TWTweetComposeViewController *tweetSheet = [[TWTweetComposeViewController alloc] init]; // Sets the completion handler. Note that we don't know which thread the // block will be called on, so we need to ensure that any UI updates occur // on the main queue tweetSheet.completionHandler = ^(TWTweetComposeViewControllerResult result) { switch(result) { case TWTweetComposeViewControllerResultCancelled: // This means the user cancelled without sending the Tweet break; case TWTweetComposeViewControllerResultDone: // This means the user hit 'Send' break; } // dismiss the Tweet Sheet dispatch_async(dispatch_get_main_queue(), ^{ [self dismissViewControllerAnimated:NO completion:^{ NSLog(@"Tweet Sheet has been dismissed."); }]; }); }; // Set the initial body of the Tweet [tweetSheet setInitialText:@"just setting up my twttr #iOS5"]; // Adds an image to the Tweet // For demo purposes, assume we have an image named 'larry.png' // that we wish to attach if (![tweetSheet addImage:[UIImage imageNamed:@"larry.png"]]) { NSLog(@"Unable to add the image!"); } // Add an URL to the Tweet. You can add multiple URLs. if (![tweetSheet addURL:[NSURL URLWithString:@"http://twitter.com/"]]){ NSLog(@"Unable to add the URL!"); } // Presents the Tweet Sheet to the user [self presentViewController:tweetSheet animated:NO completion:^{ NSLog(@"Tweet sheet has been presented."); }]; }

iOS Twitter framework

Migrating tokens to system accounts

Updated on Mon, 2011-11-07 11:13

Overview
It is very common for applications to have previously veried and stored a users access tokens, either through an existing iOS application or via a server-side integration. To leverage the power of the Twitter framework in iOS5, it is easy to migrate the user's access tokens to the device. This document details that process.

Requirements
This process requires an application running on iOS5, as well as veried access tokens and secrets for a Twitter user. The iOS target must also link against the Twitter framework and the Accounts framework.

Code Example
For this example, consider the scenario where you have already veried and securely stored your users access token and secret in an iOS application using xAuth, and would now like to migrate these tokens to the central account store. Step 1: Add Twitter.framework and Accounts.framework to your project The process for adding the Twitter framework is detailed in Adding the Twitter Framework . Follow the same instructions for adding the Accounts framework to your projects target. To verify that this step has been completed succesfully, add the following two import statements to an header le in the target project and then verify that things build successfully: 1. #import <Twitter/Twitter.h> 2. #import <Accounts/Accounts.h> Obviously, these two statements should be included in header or implementation les where classes from the two frameworks are utilized. Step 2: Add the migration code The code that transitions tokens to the account store is quite simple, but you should should check for and gracefully handle any error conditions that may arise. Note: For testing purposes, you can obtain veried tokens to use to validate this process by visiting http://dev.twitter.com/apps, and by viewing the bottom of an application page under the section entitled Your Access Token. Source Code Notes: This example utilizes Automatic Reference Counting (ARC). Extraneous line breaks are added for clarity
iOS Twitter framework

1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45. 46. 47. 48. 49. 50. 51. 52. 53. 54. 55. 56. 57. 58. 59. 60. 61. 62. 63. 64. 65.

// A previously-verified OAuth access token and secret for your user NSString *token = @"a-verified-access-token-for-your-user"; NSString *secret = @"a-verified-secret-for-your-user"; // Next, create an instance of the account store ACAccountStore *store = [[ACAccountStore alloc] init]; // Each account has a credential, which is comprised of a verified token and secret ACAccountCredential *credential = [[ACAccountCredential alloc] initWithOAuthToken:token tokenSecret:secret]; // Obtain the Twitter account type from the store ACAccountType *twitterAcctType = [store accountTypeWithAccountTypeIdentifier:ACAccountTypeIdentifierTwitter]; // Create a new account of the intended type ACAccount *newAccount = [[ACAccount alloc] initWithAccountType:twitterAcctType]; // Attach the credential for this user newAccount.credential = credential; // Finally, ask the account store instance to save the account // Note: that the completion handler is not guaranteed to be executed // on any thread, so care should be taken if you wish to update the UI, etc. [store saveAccount:newAccount withCompletionHandler:^(BOOL success, NSError *error) { if (success) { // we've stored the account! NSLog(@"the account was saved!"); } else { //something went wrong, check value of error NSLog(@"the account was NOT saved"); // see the note below regarding errors... // this is only for demonstration purposes if ([[error domain] isEqualToString:ACErrorDomain]) { // The following error codes and descriptions are found in ACError.h switch ([error code]) { case ACErrorAccountMissingRequiredProperty: NSLog(@"Account wasn't saved because " "it is missing a required property."); break; case ACErrorAccountAuthenticationFailed: NSLog(@"Account wasn't saved because " "authentication of the supplied " "credential failed."); break; case ACErrorAccountTypeInvalid: NSLog(@"Account wasn't saved because " "the account type is invalid."); break; case ACErrorAccountAlreadyExists: NSLog(@"Account wasn't added because " "it already exists."); break; case ACErrorAccountNotFound: NSLog(@"Account wasn't deleted because" "it could not be found."); break; case ACErrorPermissionDenied: NSLog(@"Permission Denied"); break; case ACErrorUnknown: default: // fall through for any unknown errors... NSLog(@"An unknown error occurred."); iOS Twitter framework

66. 67. 68. 69. 70. 71. 72.

break; } } else { // handle other error domains and their associated response codes... } } }];

Error conditions
For the ofcial iOS overview that describes how to handle error conditions, please review the Error Handling Programming Guide in the Apple Developer Library. If the token migration process is unsuccessful, there are two common error domains that may be returned: ACErrorDomain and NSURLErrorDomain. As demonstrated above, a simple switch statement can help explain any errors related to the storage of accounts, such as ACErrorAccountAlreadyExists, which indicates that you are attempting to store an account that has already been stored. The Account Store must verify the credentials it is provided by communicating with Twitter, so it is possible that the error returned is in the NSURLErrorDomain. Like all network connectivity errors, these conditions should be gracefully handled in your application. For more information on the various error codes returned in the NSURLErrorDomain, please review the contents of NSURLError.h.

Next Steps
Once you have migrated your user's tokens to core account instances, you should review API requests with TWRequest.

iOS Twitter framework

Using Reverse Auth

Updated on Thu, 2012-04-12 09:48 While the Twitter framework for iOS provides an incredibly easy way to make authenticated calls on behalf of a user to the Twitter API, you may nd the need to process a users Twitter data on your server. To faciliate this, Twitter provides an endpoint that allows you to obtain the user's OAuth tokens for your own application. The process is called Reverse Auth.

Before We Start
Reverse Auth is still OAuth.The reverse auth ow is not a complicated process, but it does require the ability to make a signed request. As such, you should be familiar with the request signing process before attempting to use the endpoint. No, seriously. Go read that document. We'll wait. Your application requires special permissions to use this endpoint.To use Reverse Auth, send a request to api@twitter.com with plenty of details about your application and why Reverse Auth is the best choice for it. The Twitter framework is required. Before we begin, you should add the Twitter framework to your project if you have not already. And of course you should ensure that the user has an account saved on the device (otherwise, this exercise will be fruitless). To do this, you can call: +[TWTweetComposeViewController canSendTweet] This will return a Boolean that indicates whether or not the user can tweet, and thus whether or not they have an account stored locally. At this point, you now have all that you need to make request an OAuth request token.

Step 1: Obtain a Special Request Token

First, you make an HTTPS request to the Twitter Request Token URL https:// api.twitter.com/oauth/request_token with your application's consumer key. In addition to the conventional oauth_* signing parameters, you must also include x_auth_mode set to the value reverse_auth. As an example, consider a request with the following values signed with the token secret ydC2yUbFaScbSlykO0PmrMjXFeLraSi3Q2HfTOlGxQM: The tokens used here are for demonstration purposes only, and will not work for you. oauth_consumer_key JP3PyvG67rXRsnayOJOcQ oauth_nonce 1B7D865D-9E15-4ADD-8165-EF90D7A7D3D2 oauth_signature_method HMAC-SHA1 oauth_timestamp 1322697052 oauth_version 1.0 x_auth_mode reverse_auth
iOS Twitter framework

These parameters should result in a signature base string that looks like this: 1. POST&https%3A%2F%2Fapi.twitter.com%2Foauth %2Frequest_token&oauth_consumer_key%3DJP3PyvG67rXRsnayOJOcQ %26oauth_nonce%3D1B7D865D-9E15-4ADD-8165EF90D7A7D3D2%26oauth_signature_method%3DHMAC-SHA1%26oauth_timestamp %3D1322697052%26oauth_version%3D1.0%26x_auth_mode%3Dreverse_auth This call should result in a response that looks like this. Notice that this response actually looks like an OAuth header. (line wrapping added for clarity): 1. 2. 3. 4. 5. 6. 7. OAuth oauth_nonce="xq2maKtilFhVTC1MSxVC4cQIJLd53O6w97YmrdOGSk8", oauth_signature_method="HMAC-SHA1", oauth_timestamp="1322697052", oauth_consumer_key="JP3PyvG67rXRsnayOJOcQ", oauth_token="5mgkU82W0PTA0DLgSIA5vFK6c08i8dXzrbLnX06vl38", oauth_signature="aOM%2FwW2kAowAeHBRvw7faH245p0%3D", oauth_version="1.0"

If you receive a response that looks like this: 1. <?xml version="1.0" encoding="UTF-8"?> 2. <errors> 3. <error code="87">Client is not permitted to perform this action</ error> 4. </errors> Your application's keys have not been enabled for reverse auth privileges. Please see the note above regarding requesting access to the endpoint.

Step 2: Obtain the Access Token

We are now going to make a request to the OAuth Access Token endpoint, https:// api.twitter.com/oauth/access_token, using the TWRequest provided by the Twitter framework. If you are not familiar with TWRequest, review API requests with TWRequest. You will need to POST to the endpoint and you must include two parameters: x_reverse_auth_target Your app's consumer key (e.g. "JP3PyvG67rXRsnayOJOcQ") x_reverse_auth_parameters The string value returned in Step #1

This code sample includes extraneous line breaks for readability, and uses Automatic Reference Counting (ARC).
1. 2. 3. 4. 5. 6. // Assume that we stored the result of Step 1 into a var 'resultOfStep1' NSString *S = resultOfStep1; NSDictionary *step2Params = [[NSMutableDictionary alloc] init]; [step2Params setValue:@"JP3PyvG67rXRsnayOJOcQ" forKey:@"x_reverse_auth_target"]; [step2Params setValue:S forKey:@"x_reverse_auth_parameters"]; iOS Twitter framework

7. 8. 9. 10. 11. 12. 13. 14. 15. 16. 17. 18. 19. 20. 21. 22. 23. 24. 25. 26. 27. 28. 29. 30. 31. 32. 33. 34. 35. 36. 37. 38. 39. 40. 41. 42. 43. 44. 45.

NSURL *url2 = [NSURL URLWithString:@"https://api.twitter.com/oauth/access_token"]; TWRequest *stepTwoRequest = [[TWRequest alloc] initWithURL:url2 parameters:step2Params requestMethod:TWRequestMethodPOST]; // You *MUST* keep the ACAccountStore alive for as long as you need an ACAccount instance // See WWDC 2011 Session 124 for more info. self.accountStore = [[ACAccountStore alloc] init]; // We only want to receive Twitter accounts ACAccountType *twitterType = [self.accountStore accountTypeWithAccountTypeIdentifier:ACAccountTypeIdentifierTwitter]; // Obtain the user's permission to access the store [self.accountStore requestAccessToAccountsWithType:twitterType withCompletionHandler:^(BOOL granted, NSError *error) { " if (!granted) { " " // handle this scenario gracefully " } else { " " // obtain all the local account instances " " NSArray *accounts = " " [self.accountStore accountsWithAccountType:twitterType]; " " // for simplicity, we will choose the first account returned - in your app, " " // you should ensure that the user chooses the correct Twitter account " " // to use with your application. DO NOT FORGET THIS STEP. " " [stepTwoRequest setAccount:[accounts objectAtIndex:0]]; " " // execute the request " " [stepTwoRequest performRequestWithHandler: ^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) { " " " NSString *responseStr = " " " [[NSString alloc] initWithData:responseData encoding:NSUTF8StringEncoding]; // see below for an example response NSLog(@"The user's info for your server:\n%@", responseStr); " " }]; " } }];

If things worked properly, you should receive a response that looks like this.
1. oauth_token=2311112785EXKeLV5ezo3HHIaIf1T3ffeww0mR5dfYXKZjjRy0&oauth_token_secret=KYxxxxx3U4Fxrxva3BGD92-12ehEzFwQ&user_id=38895958&screen_name=theseancook

iOS Twitter framework

Frequently Asked Questions

Updated on Mon, 2012-02-27 18:58 1. 2. 3. 4. 5. Frequent Asked Questions I'm receiving authentication errors when using TWRequest. What's going on? Do TWRequest and TWTweetComposeViewController calls automatically wrap urls in statuses updates? Why is my application attributed as "from iOS" instead of "from <my application>" on twitter.com? I'm seeing strange crashes when using ACAccounts with TWRequest. What is going on?

Frequent Asked Questions

The following is a collection of "gotchas" that have commonly affected developers using the Twitter.framework. If you do not see an answer to your question here, please head to the Mobile Development Discussion Forums and post your question there.

I'm receiving authentication errors when using TWRequest. What's going on?
Are you certain that there are accounts stored on the device in Settings.app? No, seriously: are you sure that there are accounts stored on the device? One of the most common errors that developers experience is that they are not checking for the existence of at least one account before calling [TWRequest setAccount:], and thus the request is sent unauthenticated. We recommend checking +[TWTweetComposeViewController canSendTweet:] before you perform any actions that may require authentication. Additionally, you can also check the size of the array returned via -[ACAccountStore accountsWithAccountType:]. Do TWRequest and TWTweetComposeViewController calls automatically wrap urls in statuses updates? Yes. Please review the documentation at t.co Link Wrapper FAQ and POST statuses/update for more information. Want to see this for yourself? You can verify this behavior on your own with the following code snippet:
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. 12. 13. ACAccountStore *store = [[ACAccountStore alloc] init]; ACAccountType *twitterType = [store accountTypeWithAccountTypeIdentifier:ACAccountTypeIdentifierTwitter]; [store requestAccessToAccountsWithType:twitterType withCompletionHandler:^(BOOL granted, NSError *error) { NSArray *accounts = [store accountsWithAccountType:twitterType]; NSURL *url = [NSURL URLWithString:@"http://api.twitter.com/1/statuses/update.json"]; NSDictionary *dict = [NSDictionary dictionaryWithObjectsAndKeys: @"This is a test https://dev.twitter.com/discussions/4682", @"status", nil]; iOS Twitter framework

14. TWRequest *request = [[TWRequest alloc] initWithURL:url 15. parameters:dict 16. requestMethod:TWRequestMethodPOST]; 17. 18. // Use the first account for simplicity 19. [request setAccount:[accounts objectAtIndex:0]]; 20. 21. [request performRequestWithHandler: 22. ^(NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error) { 23. if (responseData) { 24. id data = [NSJSONSerialization JSONObjectWithData:responseData 25. options:NSJSONReadingMutableLeaves 26. error:nil]; 27. // Print out the response. 28. // You can verify that the "text" of the status is now t.co'd. 29. NSLog(@"%@", data); 30. } 31. }]; 32. }];

Why is my application attributed as "from iOS" instead of "from <my application>" on twitter.com?
If your application is not yet live in the App Store: The application making the requests must be launched in Apple's App Store in order for the attribution to display on twitter.com. Note that the iOS5 version of the application must be live, not just a previous version. If your application is live in the App Store: In the majority of cases, your app will automatically be attributed on twitter.com. Please verify these steps if you do not see attribution: 1. 2. 3. 4. Ensure that all the elds on your iOS App Store application record are lled out and valid (e.g. valid URLs in URL elds and so on). Application names on Twitter are shorter than iOS application names. Some long iOS app names will cause attribution not to show. Don't attach "on iOS" "on iPhone" or "on iPad" to your app name Don't conict with an app name already existing and registered on dev.twitter.com.

If you have veried each of these points and you still don't have attribution, please post in the discussion forums for further support.

I'm seeing strange crashes when using ACAccounts with TWRequest. What is going on?
This is a common problem for developers who are not utilizing Automatic Reference Counting (ARC). The solution is to either use ARC in your code, or ensure that you hold onto the ACAccountStore that "owns" the ACAccount that you are using for as long as need the ACAccount. This is the same pattern that holds for such classes as ALAssetsLibrary. To quote the documentation, "The lifetimes of objects you get back from a library instance are tied to the lifetime of the library instance."
iOS Twitter framework