LYT3 POC

Design document for LYT 3

Revision 3.

LYT 3 is intended to be a hybrid app that can either run in a browser using JavaScript and some HTML5 elements or as an app on either iOS or Android. This is accomplished by keeping much of the complex logic in JavaScript, using a small native "shell" on the two platforms that provides various basic services. Those services are exposed in JavaScript through an API, hereafter named the native bridge API. The bridge is a global variable window.lytBridge.

The embedded browser in iOS apps cannot directly expose JavaScript functions that executes in the native app. As a work-around the browser-logic can store function calls on a queue and notify the native app that queue has data by requesting the URL nota://signal which will be handled transparently from the perspective of the browser, since a JavaScript object doing this will be injected on iOS.

Native bridge API

###setBook(JSON.stringify(bookData))

Saves a simplified bookData structure for the provided bookId. (Most be stringified to JSON)

bookData:

{
  'title': <book title>,
  'id': <book id>,
  'playlist': [
    { 'url': <url1>, 'start':<start1>, 'end': <end1> },
    { 'url': <url2>, 'start':<start2>, 'end': <end2> },
    ...
  ],
  'navigation': [
    {
      'name': <chapter name>,
      'offset': <offset>,
    },
    ...
  ]

clearBook(bookId)

Removes bookdata structure for the provided bookId from native app. This call will also remove any related cache files.

Possible errors:

• No such book.

getBooks()

Returns the list of books that has been provided by setBook() above:

[
  {
     'id': <book id>,
     'offset': <offset>,
     'downloaded': <downloaded>
  }
]

is just a boolean. is what the device thinks is the current offset for the book. This may be different from backend, as one or more books may have been played while the phone was offline.

play(bookId[, offset])

Starts playback of the book with the provided bookId at the given offset.

If offset is undefined, resume from last known position.

To fast forward to another part of the book, it is allowed to call this method again without calling stop() first.

Possible errors:

• No such book.
• Offset out of range.

Events:

• Timeupdate.
• End.

seek(bookId[, offset])

Seeks to the given offset without altering the play/pause state.

If offset is undefined, seek to last known position.

To fast forward to another part of the book, it is allowed to call this method again without calling stop() first.

Possible errors:

• No such book.
• Offset out of range.

Events:

• Timeupdate.
• End.

stop()

Stops any playback in progress. It is not an error to call this if no playback is in progress.

pause()

Pauses any playback in progress. It is not an error to call this if no playback is in progress.

The only difference between stop() and pause() is the semantics. Stop indicates that the user wants to stop playing this book, and might never return, while pause indicates a temporary pause.

This might offer different cache choices.

cacheBook(bookId)

Downloads book for offline playback.

Possible errors:

• No such book.

Events:

• Download progress.
• Dowload failed.
• Download completed.

cancelBookCaching(bookId)

Stops downloading book cache but leave existing cache untouched.

Possible errors:

• No such book.

clearBookCache(bookId)

Clears cached data for the provided bookId.

Possible errors:

• No such book.

getEvents()

Polling mechanism for getting events provided by the native bridge API. This is provided because it is sometimes impossible for the native app to broadcast normal JavaScript events. The events described in the methods above are available through this call.

Returns a list with the following structure:

[
  [<event name>, <parameter 1>, <parameter 2>, ... ],
  ...
]

<parameter 1> and so on are optional. is mandatory.

lytHandleEvent(eventName, parameter1, parameter2, ...)

When we do not resolve to polling the native layer will deliver events with the following function that must be defined in the web-layer.

Events

Timeupdate

This event is sent approximately every 100ms while playing. It should contain the following data:

Name: play-time-update

Param 1: bookId

Param 2: offset

Param 3: paused

---

End

This event is sent when the book has come to an end.

Name: play-end

Param 1: bookId

---

Stop

This event is sent when the book is stopped by the user.

Name: play-stop

Param 1: bookId

---

Play failed

This event is sent when playing the book failed

Name: play-failed

Param 1: bookId

Param 2: reason

---

Download progress

This event is sent every second.

Name: download-progress

Param 1: bookId

Param 2: percentage of entire download

---

Download cancelled

This event is sent when user cancels the download.

Name: download-cancelled

Param 1: book id

---

Download failed

This event is sent when the download fails. This does not mean that the download was interrupted, but that the book, for some reason, could not be downloaded.

Name: download-failed

Param 1: book id

Param 2: reason

---

Download completed

This event is sent when the download is completed.

Name: download-completed

Param 1: bookId

Param 2: timestamp

---

Connectivity changed

This event is sent when the conectivity is changed

Name: connectivity-changed

Param 1: online (boolean)