Object Model

If you’d like to completely control your users’ experience with Readmill in your application, the object model classes ReadmillUser, ReadmillBook, ReadmillReading and ReadmillReadingSession are for you:

• ReadmillUser represents a Readmill user’s account, and will be the base class for integrating with Readmill from in your application.
• ReadmillBook represents a book in the Readmill system.
• ReadmillReading represents a user’s interaction with a book, from marking it as interesting all the way through reading and completing it.
• ReadmillReadingSession represents a user sitting down and reading a book for a period of time. Your application should periodically call the -pingWithProgress:pingDuration:delegate: method on this class while the user is reading.

This part of the SDK is designed to follow your application’s flow as a user opens your app, picks a book and starts reading. Here’s how you’d integrate with Readmill at each stage:

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. Store the user's saved credentials (an example on how to do this is available in the app).

The user chooses a book to read

• Find or create the book in the Readmill service using the ReadmillUser method -findOrCreateBookWithISBN:title:author:.
• Optionally ask the user if they’d like to track their reading in Readmill and if they’d like to make their reading of this book public or private (setting this in the Settings section of your app and not asking the user each time is OK, too).
• Create a ReadmillReading object for the ReadmillBook by using the -createReadingForBook:state:isPrivate:delegate: method of the ReadmillUser class. This method will return an existing “reading” in the user’s account for the given book if it already exists, or create a new one if it does not.
• Set the state of the ReadmillReading object to ReadingStateReading using the -updateState:delegate: method to tell Readmill that the user is reading the book.

The user is reading their book

• Create a ReadmillReadingSession object using the -createReadingSession method of the ReadmillReading object. This is used to track this specific reading session.
• Periodically call the -pingWithProgress:pingDuration:delegate: method on your ReadmillReadingSession object while the user is reading. The progress is percentage represented by an integer (0-100), and pingDuration is an integer representing the duration with which you are pinging (300 seconds is the recommended interval). This informs Readmill in real-time that the user is reading the book and 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

• Set the state of your ReadmillReading object to ReadStateFinished, using -updateState:delegate: method in your ReadmillReading object to tell Readmill that the user has finished their book.
• Optional, but recommended: Ask the user to provide a “closing remark” for the book — a mini-review, if you will, and tell Readmill using the -updateClosingRemark:delegate: method of ReadmillReading. This really helps enhance the social aspect of Readmill.

Try it out

The sample iPad application provided with the SDK uses the model objects of the SDK in places, 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.