SVShareViewController

h1. SVShareViewController

SVShareViewController is a simple compose UI for posting textual content to 3rd party services like Facebook and Twitter. It doesn't include the network classes that will make the actual API calls. For that, you'll have to work with the "Facebook iOS SDK":https://github.com/facebook/facebook-ios-sdk and "MGTwitterEngine":https://github.com/mattgemmell/MGTwitterEngine.

!http://samvermette.com/files/svshareviewcontroller2.png!

h2. Installation

• Drag the @SVShareViewController/SVShareViewController@ folder into your project.
• Add the QuartzCore framework to your project.

h2. Usage

SVShareViewController currently supports 2 services: Facebook (@SVShareTypeFacebook@) and Twitter (@SVShareTypeTwitter@). You specify the used service via its @initWithShareType:@ method. You also need to set its delegate (that handles the sending of messages and user signout). Finally, it is recommended that you set the @userString@ (usually retrieved from initial sign in and then stored locally — more on that later) and @defaultMessage@ properties. The following code snippet is the typical way to setup and present an SVShareViewController instance:

h2. Adopting the SVShareViewControllerDelegate protocol

SVShareViewController provides UI controls for 2 actions: sending the message and logging out. You are required to adopt both delegate methods (presumably inside the view controller that presents the SVShareViewController instance):

h3. Responding to the "Send" action

This is where you make the API calls using either the "Facebook iOS SDK":https://github.com/facebook/facebook-ios-sdk or "MGTwitterEngine":https://github.com/mattgemmell/MGTwitterEngine (or any other API wrapper of your chosing), depending on the current @shareType@. Other typical tasks to be executed from within this delegate method:

• Show a progress HUD to let the user know what's going on (cough "SVProgressHUD":https://github.com/samvermette/SVProgressHUD cough)
• Append a link to the tweet or the facebook post
• Validate the user input (for instance make sure the string doesn't exceed 140 characters for tweets)
• Dismiss the SVShareViewController instance (on request success)

h3. Responding to the "Logout" action

Although SVShareViewController doesn't provide a sign in mechanism, it provides a "Logout" button along with a corresponding delegate method. The latter typically involves 2 required actions:

• Make the appropriate API calls that make the session tokens invalid
• Clear locally stored session variables (in @NSUserDefaults@ for instance)

h2. User authentication mechanisms

To make SVShareViewController more flexible, I decided not to include Facebook and Twitter API wrappers into this project. That being said, here are some rough walkthroughs of how they should be interacting with SVShareViewController:

h3. Facebook authentication

The official "Facebook iOS SDK":https://github.com/facebook/facebook-ios-sdk is the only way to integrate Facebook into your app. The class at its core is @Facebook@, and it has a @isSessionValid@ method to check whether the user is already signed in. When that method returns @NO@, user is presented with a modal webview that prompts him for credentials. On successful login, the @fbDidLogin@ delegate method gets called. This is where you should:

• make an API call to Facebook to "retrieve the user's fullname":http://developers.facebook.com/docs/reference/api/user/ and store it locally;
• grab the @accessToken@ and the @expirationDate@ properties from your @Facebook@ instance and store them locally, that way the user stays signed in for as long as the expirationDate isn't reached (make sure you assign them back everytime you create a new @Facebook@ instance though)
• present your @SVShareViewController@ instance, after setting its @userString@ property using the previously stored name value.

h3. Twitter authentication

Twitter is much more flexible in terms of sign in and API wrappers. For signing in, there are many web-based solutions out there, which ask for Twitter credentials and then requires the user to copy/paste an access pin. This is terrible UX. To allow native sign in and most importantly not ask the user to copy paste any bit of information, you'll need to "enable XAuth access for your app":https://dev.twitter.com/pages/xauth. Once that's done, you can then use "MGTwitterEngine":https://github.com/mattgemmell/MGTwitterEngine to make both the authentification and other API calls. On successful sign in, the @accessTokenReceived:forRequest:@ will be called. This is where you should:

• make an API call to Twitter to retrieve the username (using MGTwitterEngine's @checkUserCredentials@ method) and store it locally;
• grab the (OAuth) @key@ and @secret@ from the returned @OAToken@ and store them locally, that way the user stays signed in for as long they're valid (make sure you assign them through the @accessToken@ property everytime you create a new @MGTwitterEngine@ instance though)
• present your @SVShareViewController@ instance, after setting its @userString@ property using the previously stored name value.