The official iOS SDK includes a framework that enables your iOS applications to leverage the power of Twitter. This framework removes many of the common obstacles encountered when accessing Twitter's API, including authentication and Tweet composition, and allows developers to focus on more meaningful levels of integration that enrich their applications' experiences.
Note: With the Social 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.
What can I do with the framework?
As a mobile application developer, there are 3 key facets of Twitter that you can leverage in your applications:
- 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.
Single Sign-On
On iOS, a user's Twitter credentials are stored in a central account store, ACAccountStore, that is accessible from applications on the device. The first 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:
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-verified OAuth tokens and secrets to add the user's 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
Once a user's 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.
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.
Distribution
The Social framework contains a standard, easy-to-invoke dialog for composing Tweets, SLComposeViewController. This view controller is the modern version of the original version from the Twitter.framework, TWTweetComposeViewController.
Note: You should migrate any projects that use Twitter.framework to the Social.framework.
This view controller, when configured for posting to Twitter, 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 user's 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.
The Tweet Sheet
Instant Personalization
Mobile devices provide valuable signals that can be used to personalize and enrich a user's 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 application's experience for a user based on the user's 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 first time. At this point, you know very little about the user, but if the user has a Twitter account configured on the device, you can quicklyand easilysurface 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 Social framework provides SLRequest which encapsulates requests to Twitter's REST API while seamlessly handling user authentication. With SLRequest, 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, SLRequest is documented with examples at API requests with SLRequest.
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 flow to obtain the user's permission. You should then use the returned access token and secret for future calls that require DM read permission.
Documentation, example and forums
Apple's Developer Library includes many guides and references that can assist you if you need help. Before attempting to build an iOS Twitter integration, it is highly recommended that you review the following:
- The Social framework documents the classes in the framework. (iOS6+)
- The Twitter Framework Reference documents the classes in the framework. (iOS5+)
- The Account Framework Reference documents the Account framework, which is used in conjunction with Twitter.framework.
- The official 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.
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.