EasySocial iOS Library for Twitter and Facebook

This library allows your apps to use Twitter and Facebook with minimal understanding of the relevant SDK. It is super easy to use and elegantly designed. It will save you time.

Many other libraries are overly complicated and offer functionality that you do not need in your app. The included Example Project demonstrates most of the features offered.

EasySocial does only these things:

Twitter

• Send Plain Tweets
• Send Tweets with images (via a URL or UIImage/NSData)
• Get Data from user's timeline

Facebook

• Full Facebook Connect (Log In/Log Out and Auto-Log In)
• Fetch User Information (objectID, name etc...)
• Share and Publish messages in user's timeline

Installation

CocoaPods

pod 'EasySocial', '~> 1.0'

First Part

1. Add

   Social.framework

   to your project
2. Add

   Accounts.framework

   to your project
3. Drag the

   EasySocial

   folder into your project (Ensure you check

   Copy items into destination group's folder

   )
4. Open

   -Prefix.pch

   file in the

   Supporting Files

   Folder within XCode. For XCode 6, you will need to create a

   pch

   file from scratch.
   • Add to the bottom:

//Now you do not need to include those headers anywhere else in your project.
#import "EasyFacebook.h"
#import "EasyTwitter.h"

Second Part

1. Download and Add

   FacebookSDK.framework

   into your project.
2. Register your app with Facebook to get an App ID
   • Ensure that the

     Bundle ID

     you give your app on XCode matches what you register with Facebook
   • Ensure that you enable

     "Single Sign On"

     in Facebook
   • Configure the

     -Info.plist

     file by inserting

     FacebookAppID

     ,

     FacebookDisplayName

     and

     URL types

     keys
   • Register your own facebook account as a

     Developer

     account. That way you can test your app while you are developing it. In production, Facebook must approve your app to use some features
3. In your project's

   AppDelegate.m

   file, include:

- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation
{
    BOOL wasHandled1 = [EasyFacebook handleOpenURL:url sourceApplication:sourceApplication];
//  BOOL wasHandled2 = [GPPURLHandler handleURL:url sourceApplication:sourceApplication annotation:annotation];
//  BOOL wasHandled3 = [TumblrAPI handleURL:url];

return wasHandled1;
//  return (wasHandled1 || wasHandled2 || wasHandled3);
}

EasyTwitter

Methods

Before you can use EasyTwitter, you must instantiate the

EasyTwitter

+ (EasyTwitter *)sharedEasyTwitterClient

The class is a singleton class meaning only one is ever created. In practice, the class is automatically instantiated without any action on your part. You can use the class by typing:

[EasyTwitter sharedEasyTwitterClient].XXX

[[EasyTwitter sharedEasyTwitterClient] XXX].

Methods - Requesting Permission & Setting Account

Before your app can use Twitter, the user must grant permission to your app.

- (void)requestPermissionForAppToUseTwitterSuccess:(void(^)(BOOL granted, BOOL accountsFound, NSArray *accounts))success failure:(void(^)(NSError *error))failure

BOOL granted

Settings

Privacy

Twitter

BOOL accountsFound

granted==YES

Settings

Twitter

NSArray *accounts

ACAccount

ACAccount

• ACAccount

  contains two properties that are useful:
  • .username (Type:string i.e finkd)
  • .accountDescription (Type:string i.e. @finkd)

Once you discover the required account, set it.

//In practice, set it to the required account. This is the default setting automatically set.
[EasyTwitter sharedEasyTwitterClient].account = [accounts firstObject];

Methods - Sending Tweets

A Tweet is a (max) 140 character

message

message.

//Plain Tweet
- (void)sendTweetWithMessage:(NSString *) message twitterResponse:(void(^)(id responseJSON, NSDictionary *JSONError, NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error))response failure:(void(^)(EasyTwitterIssues issue))failure
//Tweet with an image in *NSData format
- (void)sendTweetWithMessage:(NSString *) message image:(NSData *) image mimeType:(NSString *) mimeType requestShowLoadScreen:(BOOL) show twitterResponse:(void(^)(id responseJSON, NSDictionary *JSONError, NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error))response failure:(void(^)(EasyTwitterIssues issue))failure
//Tweet with an image referred to by a URL
- (void)sendTweetWithMessage:(NSString *) message imageURL:(NSURL *) imageURL twitterResponse:(void(^)(id responseJSON, NSDictionary *JSONError, NSData *responseData, NSHTTPURLResponse *urlResponse, NSError *error))response failure:(void(^)(EasyTwitterIssues issue))failure

(NSString *) message

(NSData *) image

UIImage

NSData

UIImageJPEGRepresentation()

UIImagePNGRepresentation().

(NSString *) mimeType

image/png,

image/jpeg,

image/gif.

image/png

(NSURL *) imageURL

(BOOL) show

YES.

NSDictionary *JSONError

JSONError == nil,

nil,

The issue can be determined by reading the error code and error message.

//pseudo code
int errorCode = [[JSONError objectForKey:@"code"] intValue]; //JSON error code as opposed to HTTP error code
NSString *errorMessage = [JSONError objectForKey:@"message"];

Common Error Codes:

• 187 indicates a duplicate tweet.
• 186 indicates the tweet was too long (over 140 characters).

EasyTwitterIssues issue

failure

If

issue == EasyTwitterNoAccountSet,

Methods - Timeline

A user's

home-timeline

home-timeline

user-timeline.

- (void)loadTimelineWithCount:(int) count completion:(void (^)(NSArray *data, NSError *error))completion

(int) count

NSArray *data

NSDictionary

index==0.

NSLog(@"data: %@", data)

Finally you can extract the desired data like this:

//pseudo code
cell.textLabel.text = [data[row] objectForKey:@"text"]; //Main contents of item
cell.detailTextLabel.text = [[data[row] objectForKey:@"user"] objectForKey:@"""screen_name"""]; //Screen name of owner of item

Notifications

EasyTwitterPermissionGrantedNotification

EasyTwitterAccountSetNotification

ACAccount

EasyTwitterTweetSentNotification

NSDictionary *JSONError

response

sendTweetWithMessage:

nil

EasyTwitterDelegate

Both methods prescribed in the protocol are

optional.

delegate

Example Project.

showLoadingScreen:

hideLoadingScreen:

It is expected that you show the user that background activity is occurring via a UI element.

The delegate methods are called before and after:

• requestPermissionForAppToUseTwitterSuccess:failure:

• sendTweetWithMessage:image:mimeType:requestShowLoadScreen:twitterResponse:failure:

• sendTweetWithMessage:imageURL:twitterResponse:failure:

• sendTweetWithMessage:twitterResponse:failure:

• loadTimelineWithCount:completion:

EasyFacebook

Methods

Before you can use EasyFacebook, you must instantiate the

EasyFacebook

+ (EasyFacebook *)sharedEasyFacebookClient

The class is a singleton class meaning only one is ever created. In practice, the class is automatically instantiated without any action on your part. You can use the class by typing:

[EasyFacebook sharedEasyFacebookClient].XXX

[[EasyFacebook sharedEasyFacebookClient] XXX].

Methods - Log in & Log out

Before you can interact with the FacebookSDK, you must have a logged in user.

- (void)openSession  //For logging in
- (void)closeSession //For logging out
- (BOOL)isLoggedIn   //For checking logged in status

By calling the

openSession

openSession

The

closeSession

The

(BOOL)isLoggedIn

If the user logs in and later exits your app, a cached token will usually be saved locally. When your app is opened again, the user will usually not have to log in again. This is part of the Auto-Log In feature.

For security reasons, if you want to turn off Auto-Log In behaviour, you can listen to UIApplicationWillTerminateNotification and call

closeSession

When the user is being logged in, the FacebookSDK requires the initial permissions requested. The default permissions are:

• public_profile

• email

• user_friends

If you want to modify the permissions requested, before calling

openSession

readPermissions:

//Set the readPermissions to what ever you want
[EasyFacebook sharedEasyFacebookClient].readPermissions = @[@"public_profile", @"email", @"user_friends"];

Read the

Notifications

Methods - Fetching basic user information

After the user logs in, a call to fetch the user's basic information is automatically done. However, if you want the latest information on demand then call this method.

- (void)fetchUserInformation

Once the information arrives, the

EasyFacebookUserInfoFetchedNotification

• @property NSString *UserEmail

  - Only available if

  email

  permission is requested. By default, it is requested.

• @property NSString *UserFirstName

• @property NSString *UserGender

• @property NSString *UserObjectID

  - usually referred to as

  id

  (unique to the user - store in databases)

• @property NSString *UserLastName

• @property NSString *UserLink

• @property NSString *UserLocale

• @property NSString *UserName

• @property NSString *UserTimeZone

• @property NSString *UserVerified

Methods - Publishing Rights

Publishing to the timeline requires the

publish_actions

- (BOOL)isPublishPermissionsAvailableQuickCheck
- (void)isPublishPermissionsAvailableFullCheck:(void(^)(BOOL result, NSError *error))responseHandler
- (void)requestPublishPermissions:(void(^)(BOOL granted, NSError *error))responseHandler

(BOOL)isPublishPermissionsAvailableQuickCheck

publish_actions

access token.

access token

(void)isPublishPermissionsAvailableFullCheck

publish_actions

BOOL result

result==YES,

If publishing permission is not available, you will have to request it by calling

(void)requestPublishPermissions

granted==YES

Methods - Publishing Content

To publish and share content,

publish_actions

publishStoryWithParams:completion:

requestPublishPermissions:

- (void)publishStoryWithParams:(NSDictionary *)params completion:(void(^)(BOOL success, NSError *error))completion

(NSDictionary *)params

• link - the url we want to share
• name - a title
• caption - a subtitle
• picture - the url of a thumbnail to associate with the post
• description - a snippet of text describing the content of the link
• message - main message appears above everything else

BOOL success

completion

success==YES,

As an example:

NSDictionary *params = @{@"link" : @"http://www.google.com",
                         @"name" : @"Google",
                         @"caption" : @"#1 search engine",
                         @"picture" : @"https://www.google.com/images/srpr/logo11w.png",
                         @"description" : @"Home page Logo",
                         @"message" : @"hello"
                        };

The output will be:

Notifications

EasyFacebookLoggedInNotification

EasyFacebookLoggedOutNotification

EasyFacebookUserInfoFetchedNotification

fetchUserInformation

EasyFacebookUserCancelledLoginNotification

EasyFacebookPublishPermissionGrantedNotification

EasyFacebookPublishPermissionDeclinedNotification

EasyFacebookStoryPublishedNotification

EasyFacebookDelegate

Both methods prescribed in the protocol are

optional.

delegate

Example Project.

showLoadingScreen:

hideLoadingScreen:

It is expected that you show the user that background activity is occurring via a UI element.

The delegate methods are called before and after:

• publishStoryWithParams:completion:

Diagnostics

@property BOOL preventAppShutDown

YES.

@property BOOL facebookLoggingBehaviourOn

YES.

Final Notes

If you found this library useful, please Star it on github. Feel free to fork or provide pull requests. Any bug reports will be warmly received.