ReadSocial is a service that adds social features to your content quickly and easily. Learn more

The Objective-C library takes care of the common tasks required to enable social reading within your iOS application. This is project includes the code library, the UI, and shows its implementation in a sample app.

If you just want to see ReadSocial in action, simply download and build the sample project (requires iOS 5). It will demo the ReadSocial API Objective-C library using the article As We May Think, by Vannevar Bush. We encourage you to use the web demo at the same time so you can get a feel for how different clients on different platforms can interct with the ReadSocial platform.

There are two parts to the library: the API--which handles communication and data between the app and the server, and the UI--which allows the user to interact with the service. You'll need to copy both sections of code into your app (the API and UI directories are located inside the ReadSocial folder).

In your AppDelegate, initialize ReadSocial with the settings you want, including:

• Network ID
• Default group
• UI library to use

For example:

#import "ReadSocialAPI.h"
#import "ReadSocialUI.h"

[ReadSocial initializeWithNetworkID : [NSNumber numberWithInt:8]
            defaultGroup            : @"partner-testing-channel" 
            andUILibrary            : [ReadSocialUI library]
            ];

Although your content may not conform to a typical "page" as most users may think of, a "page" in this case simply refers to a collection of paragraphs. It may be one screen full, one chapter full, or literally one page full. It's up to you!

For example:

[ReadSocial setCurrentPageAndDelegate:self];

(where self is a UIViewController).

ReadSocial needs to know where how to get the content your user is interacting with. You do that by implementing the ReadSocialDataSource protocol and defining the following methods:

• - (NSInteger) numberOfParagraphsOnPage;
• - (NSString *) paragraphAtIndex: (NSInteger)index;
• - (CGRect) rectForParagraphAtIndex: (NSInteger)index;
• - (NSInteger) paragraphIndexAtSelection;
• - (NSString *) selectedText;

See ViewController.m for an example of how to implement these methods.

People will interact more if they see that people have already commented on a paragraph. The ReadSocial API and UI Library provide an easy way to add a note count to each paragraph.

Make sure your view controller is implementing the ReadSocialDelegate protocol and implement the - (void) noteCountUpdatedForParagraph:(RSParagraph *)paragraph atIndex:(NSInteger)index method. This will get triggered every time the note count is updated for a given paragraph. Look at ViewController.m for an example of how to implement it.

Another powerful way ReadSocial allows users to interact with your content is through selecting text. Add a UIMenuItem that will trigger [ReadSocial openReadSocialForSelectionInView:self.view];.

If your app needs to supply it's own user authentication and simply send the user data to the ReadSocial server instead of relying on authentication from one of the three default providers, then you need to specify both your app's identifier and app secret key in the app delegate.

[[ReadSocial sharedInstance] setAppKey:@"fSxua20klUTHGvq0TPHF8CVHtFI6SVTwJepRU6bl"];
[[ReadSocial sharedInstance] setAppSecret:@"8iwQBJDIfslTRhs8wR1DJ3pRNpcviq53BLqTm5dO"];

Once you specify your own app key and secret, you need to specify the current user before POSTing data to the server.

[[ReadSocial sharedInstance] setCurrentUser:[RSUser userWithID:@"9999" andName:@"Display Name" andImageURL:[NSURL URLWithString:@"https://www.readsocial.net/images/demo-avatar.png"] forDomain:@"example.com"]];

• User ID--Any identifier for the user. Must be unique within your app.
• Display Name--The display name for the user. Will be displayed next to user's submissions.
• Image URL--The URL where the user's profile image can be found.
• Domain--The user's domain.

ReadSocial uses Core Data to organize and store data from the service and from the user. Currently, it requires that the implementing app start with the Core Data Xcode template. We're working to remove this requirement very soon.

The ReadSocial Demo (and the library of code within the demo) rely on Automated Reference Counting (ARC) within iOS 5.