Using Readmill-provided UI

For the simplest integration with Readmill for an eBook reader style of application, the Readmill SDK provides its own UI to allow users of your application to link their books to Readmill’s service.

• Figure 1: An example of the Readmill SDK’s book linking UI.
• Figure 2: An example of the Readmill SDK’s book view reading UI.

The user launches your application

• If the user has logged into Readmill through your application before, create a ReadmillUser object from saved credentials.
• If the user hasn’t logged into Readmill through your application before, allow the user to log in through the Readmill website and create a ReadmillUser object from the returned authorisation information.

The user chooses a book to read

• Create the ReadmillConnectBookUI with -initWithUser:ISBN:title:author:. Bring up a dialog where the user can connect the book to the Readmill service by instantiating a ReadmillUIPresenter with the ReadmillConnectBookUI as contentViewController and calling -presentInViewController:animated:.
• If the user connected their book to their Readmill account, the ReadmillConnectBookUI class will provide the ReadmillReading object through its delegate method -connect:didSucceedToLinkToBook:withReading:, which represents the user’s overall interaction with the book. Use the -createReadSession method on this object to create a new ReadmillReadingSession object, which represents this specific reading session.

The user is reading their book

• Periodically call the -pingWithProgress:pingDuration:delegate: method on your ReadmillReadingSession object, where progress is percentage as a float (0-1), and pingDuration is the interval (in seconds) which with you are pinging (300s is the recommended interval). This informs Readmill in real-time that the user is reading the book and of the progress they are making.

The user stops reading their book, but hasn’t finished

• There’s nothing further to do. When you stop calling -pingWithProgress:, Readmill will automatically do the right thing and understand that the user isn’t reading any more.

The user reaches the end of their book

• Use the ReadmillViewReadingUI class in combination with the ReadmillUIPresenter class to present a Readmill user interface to the user to allow them to mark their book as finished in their Readmill account and optionally set a closing remark — a mini-review, if you will.

Try it out

The sample iPad application provided with the SDK goes through this entire workflow, including saving login credentials and authenticating with the Readmill website. To get started, check it out — the Xcode project provides everything you need to integrate with Readmill, and all the class headers in the Readmill SDK are documented if you need more help.