Read It Later API: iPhone Library

If you are adding sharing to your app, I highly recommend you check out ShareKit instead. It has a lot of great features and supports Read It Later in addition to a number of other services.

The Read It Later iPhone Library lets you add complete Read It Later support to your app with just 2 lines of code!
Complete means users will be able to save pages, login, or signup without leaving your application.

Two versions of the library are provided:

  • Full - Drop-in solution that displays loading screens and forms on top of your existing interface.
  • Lite - Basic methods to save, login, and signup. Use if you'd like to provide your own interface.

 

Full Library: Provides the Interface For You

Download | Quick Install | Complete Documentation

Quick Install

You can have Read It Later fully integrated in a matter of minutes. Follow these instructions for a quick setup.
Take a look at the example project provided in the downloaded zip for an example.

Step 1: Add Files to Project

Drag the four class files from the downloaded zip into your project's Classes folder in Xcode.

Step 2: Add Import Line

Add this line to the top of any file that implements functions from the API:

#import "ReadItLaterFull.h"

Step 3: Add Your API Key

Update the top of the ReadItLaterLite.m file to include your API Key.

static NSString *apikey = "yourKey";

Step 4: Add the Save Function

Wherever you have a link you want to save to Read It Later, add the following line: In this example, we save google.com

[ReadItLater save:[NSURL urlWithString:@"http://google.com"] title:@"Google"];

Step 5: Add the Login Screen (optional)

If the user has not logged in or signed up yet, when you call the save function it will popup a login/signup window first. If you'd like to open this window somewhere else in your interface, for example a button on your settings page, call this function to display it:

[ReadItLaterFull showUserSetup];

That's It!

User's will now be able to save to Read It Later, login or create an account all without leaving your app!

Complete Documentation for Full Library

+(void)save:(NSURL *)url title:(NSString *)title

Saves the provided url and title to the user's list. Displays a loading screen and notifies the user if request succeeds or fails. The user's username and password is assumed to be stored in NSUserDefaults in the keys 'ReadItLaterUsername' and 'ReadItLaterPassword'. See the next method if you'd like to provide the username/password yourself. If you use the provided interface for managing logins/signups, the username/password will be stored for you already. If the username and password are not stored yet, the login screen will be displayed.

Parameters
  • url - NSURL - link to the page to save
  • title - NSString - (optional nil) - title of the page you are saving. For the best user experience please provide a unique way of identifying the link. [Read More]

Example:
[ReadItLaterFull save:[NSURL urlWithString:@"http://google.com"] title:@"Google"];

+(void)save:(NSURL *)url title:(NSString *)title username:(NSString *)username password:(NSString *)password;

Saves the provided url and title to the user's list. Displays a loading screen and notifies the user if request succeeds or fails.

Parameters
  • url - NSURL - link to the page to save
  • title - NSString - (optional nil) - title of the page you are saving. For the best user experience please provide a unique way of identifying the link. [Read More]
  • username - NSString - User's Read It Later username
  • password - NSString - User's Read It Later password

Example:
[ReadItLaterFull save:[NSURL urlWithString:@"http://google.com"] title:@"Google" username:@"myUsername" password:@"myPassword"];

+(void)showUserSetup;

Displays a login/signup screen. Allows the user to login or create an account.

Example:
[ReadItLater showUserSetup];

 

Lite Library: Make Requests to RIL API With Your Own Interface

Download | Install | Complete Documentation

Install

Step 1: Add Files to Project

Drag the ReadItLaterLite class files from the downloaded zip into your project's Classes folder in Xcode. You do not need ReadItLaterFull.h or ReadItLaterFull.m

Step 2: Add Import Line

Add this line to the top of any file that implements functions from the API:

#import "ReadItLaterLite.h"

Step 3: Add Your API Key

Update the top of the ReadItLaterLite.m file to include your API Key.

static NSString *apikey = "yourKey";

Step 4: Add Save/Login/Signup Functions

Each method only requires one line. After the request completes it will return a status code to your provided delegate.

[ReadItLater save:[NSURL urlWithString:@"http://google.com"] title:@"Google" delegate:self];

[ReadItLater authWithUsername:@"myUsername" password:@"myPassword" delegate:self];

[ReadItLater signupWithUsername@"myUsername" password:@"myPassword" delegate:self];

Complete Documentation for Lite Library

+(void)save:(NSURL *)url title:(NSString *)title delegate:(id)delegate username:(NSString *)username password:(NSString *)password;

Saves the provided url and title to the user's list.

Parameters
  • url - NSURL - link to the page to save
  • title - NSString - (optional nil) - title of the page you are saving. For the best user experience please provide a unique way of identifying the link. [Read More]
  • delegate - id - Your object that implements the Read It Later delegate protocol.
  • username - NSString - User's Read It Later username
  • password - NSString - User's Read It Later password

Example:
[ReadItLater save:[NSURL urlWithString:@"http://google.com"] title:@"Google"];
Response:

When finished, message is sent to delegate on readItLaterSaveFinished: selector.

+(void)authWithUsername:(NSString *)username password:(NSString *)password delegate:(id)delegate;

Checks to see if a provided username and password matches an account with Read It Later.

Parameters
  • username - NSString - User's Read It Later username
  • password - NSString - User's Read It Later password
  • delegate - id - Your object that implements the Read It Later delegate protocol.

Example:
[ReadItLater authWithUsername:@"myUsername" password:@"myPassword" delegate:self];
Response:

When finished, message is sent to delegate on readItLaterLoginFinished: selector.

+(void)signupWithUsername:(NSString *)username password:(NSString *)password delegate:(id)delegate;

Trys to register a new Read It Later account with the provided username and password

Parameters
  • username - NSString - User's Read It Later username
  • password - NSString - User's Read It Later password
  • delegate - id - Your object that implements the Read It Later delegate protocol.

Example:
[ReadItLater signupWithUsername:@"myUsername" password:@"myPassword" delegate:self];
Response:

When finished, message is sent to delegate on readItLaterSignupFinished: selector.

Delegate Methods

The delegate you pass to the save/login/signup methods should implement the following: 

@protocol ReadItLaterDelegate 
-(void)readItLaterSaveFinished:(NSString *)stringResponse error:(NSString *)errorString;
-(void)readItLaterLoginFinished:(NSString *)stringResponse error:(NSString *)errorString;
-(void)readItLaterSignupFinished:(NSString *)stringResponse error:(NSString *)errorString;
@end
  • stringResponse - NSString - The actual data returned. You only need to look at this for methods like get that return something other than success or failure.
  • errorString - NSString - If nil the request was successful. Otherwise, this will contain a message to display to the user with the reason it failed.

 

Extra Notes

Titles

Providing a title is very helpful to the user so they know what the link added to their list is for. If you have the page open in a UIWebView that you are saving, you can grab the title with:

NSString *title = [webView stringByEvaluatingJavaScriptFromString:@"document.title"];

Account - Signup

If you provide the user with the ability to signup for RIL directly inside the app, I strongly recommend providing a way for the app to email their account information. See TwitterFon Free for a nice example of this.

The Full library provides a button to do this, but if you are using iPhone 3.0, it is suggested to replace this with the in-app email support so the user does not have to leave your app.

 

Download

The library download provides both the Lite and Full classes (2 files each) in addition to an example project that implements both libraries.

Download Library and Example Project

I just updated this, so please let me know if you have any issues.