Proposal for OPDS callbacks

[Hadrien Gardeur]

Hey everyone,

After exchanging emails with a lot of people working on both native and web apps, here's a first proposal and a full example on how we could handle callbacks.

1. Discovering a book

A client displays the following entry to the user:

<entry>
  <title>The Help</title>
  <id>http://www.feedbooks.com/item/53936</id>
  <dcterms:identifier xsi:type="dcterms:URI">urn:ISBN:9781440697661</dcterms:identifier>
  <dcterms:identifier xsi:type="dcterms:URI">urn:ISBN:9780399155345</dcterms:identifier>
  <author>
    <name>Kathryn Stockett</name>
    <uri>http://www.feedbooks.com/search?query=contributor%3A%22Kathryn+Stockett%22</uri>
  </author>
  <published>2011-02-11T17:26:39Z</published>
  <updated>2011-08-10T08:10:02Z</updated>
  <dcterms:language>en</dcterms:language>
  <dcterms:publisher>Putnam Adult</dcterms:publisher>
  <dcterms:issued>2009-08-19</dcterms:issued>
  <summary>Be prepared to meet three unforgettable women:  Twenty-two-year-old Skeeter has just returned home after graduating from Ole Miss. She may have a degree, but it is 1962, Mississippi, and her mother will not be happy till Skeeter has a ring on her ...</summary>
  <dcterms:extent>446 KB</dcterms:extent>
  <category label="Fiction" term="FBFIC000000"/>
  <category label="Literary" term="FBFIC019000"/>
  <link type="text/html" title="View on Feedbooks" rel="alternate" href="http://www.feedbooks.com/item/53936"/>
  <link type="image/png" rel="http://opds-spec.org/image" href="http://covers.feedbooks.net/item/53936.jpg?t=1312963802"/>
  <link type="image/png" rel="http://opds-spec.org/image/thumbnail" href="http://covers.feedbooks.net/item/53936.jpg?size=thumbnail&amp;t=1312963802"/>
  <link type="text/html" rel="http://opds-spec.org/acquisition/buy" href="https://www.feedbooks.com/item/53936/buy">
    <opds:price currencycode="USD">9.99</opds:price>
    <opds:indirectAcquisition type="application/vnd.adobe.adept+xml">
      <opds:indirectAcquisition type="application/epub+zip"/>
    </opds:indirectAcquisition>
  </link>
  <link type="application/atom+xml;type=entry" title="Full entry" rel="alternate" href="http://www.feedbooks.com/item/53936.atom"/>
</entry>

The user is interested and decides to buy the book.

2. Following the link (Native Application)

For a native app, there's nothing really special required aside from following the acquisition link.

2. Following the link (Web Application)

For a web applications, things are slightly more complicated (but not that much).

In this case, the acquisition link is https://www.feedbooks.com/item/53936/buy. To enable an OPDS callback, the Web App has to append an "opds_callback" query parameter along with the URL where the user will be redirected at the end of the transaction. 

For example we could use the following callback: https://fr.feedbooks.com/item/53936/buy?opds_callback=http://www.opds-app.com?callback=

3. After the transaction (Native Application)

At the end of the transaction, the catalog provider displays a callback button using the opds scheme.

This link, MUST start with opds://acquire/ and link to a full OPDS entry. This OPDS entry MUST NOT require any kind of authentication. Catalog providers MAY use a time-sensitive URL to protect the content.

For our example, this could be: opds://acquire/www.feedbooks.com/item/53936.atom?hash=66466884463897923

3. After the transaction (Web Application)

At the end of the transaction, the catalog provider displays a callback button too, using the callback URL previously provided by the Web App.

In our example this would be a link to http://www.opds-app.com?callback=opds://acquire/www.feedbooks.com/item/53936.atom?hash=66466884463897923

The same restrictions about the OPDS entry apply to this callback.

4. Acquiring the publication

The client opens the link to the OPDS entry. For our example this could be:

<entry>
  <title>The Help</title>
  <id>http://www.feedbooks.com/item/53936</id>
  <dcterms:identifier xsi:type="dcterms:URI">urn:ISBN:9781440697661</dcterms:identifier>
  <dcterms:identifier xsi:type="dcterms:URI">urn:ISBN:9780399155345</dcterms:identifier>
  <author>
    <name>Kathryn Stockett</name>
    <uri>http://www.feedbooks.com/search?query=contributor%3A%22Kathryn+Stockett%22</uri>
  </author>
  <published>2011-02-11T17:26:39Z</published>
  <updated>2011-08-10T08:10:02Z</updated>
  <dcterms:language>en</dcterms:language>
  <dcterms:publisher>Putnam Adult</dcterms:publisher>
  <dcterms:issued>2009-08-19</dcterms:issued>
  <summary>Be prepared to meet three unforgettable women:  Twenty-two-year-old Skeeter has just returned home after graduating from Ole Miss. She may have a degree, but it is 1962, Mississippi, and her mother will not be happy till Skeeter has a ring on her ...</summary>
  <dcterms:extent>446 KB</dcterms:extent>
  <category label="Fiction" term="FBFIC000000"/>
  <category label="Literary" term="FBFIC019000"/>
  <link type="text/html" title="View on Feedbooks" rel="alternate" href="http://www.feedbooks.com/item/53936"/>
  <link type="image/png" rel="http://opds-spec.org/image" href="http://covers.feedbooks.net/item/53936.jpg?t=1312963802"/>
  <link type="image/png" rel="http://opds-spec.org/image/thumbnail" href="http://covers.feedbooks.net/item/53936.jpg?size=thumbnail&amp;t=1312963802"/>
  <link type="application/vnd.adobe.adept+xml" rel="http://opds-spec.org/acquisition" href="https://www.feedbooks.com/item/53936/download?hash=65464666346913826">
    <opds:indirectAcquisition type="application/epub+zip"/>
  </link>
</entry>

You'll notice that unlike the first OPDS entry that we used before the transaction, this one includes a link directly to the .acsm file this time and not a web page.

The client can therefore directly download the publication using this entry.

Would this work for everyone ? Any feedback is welcome ;-)

Hadrien

[Tim Jones]

Looks good to me. :)

Cheers,

Tim

--
You received this message because you are subscribed to the Google
Groups "Open Publication Distribution System" group.
 
To post to this group, send email to ope...@googlegroups.com
To unsubscribe from this group, send email to
openpub+u...@googlegroups.com
 
For more options, visit this group at
http://groups.google.com/group/openpub?hl=en

[Dave Thomas]

1. Is the assumption that the document is immediately available for download? In our case, we custom prepare each ebook for each customer, so there's sometimes a delay.

2. What is the assumed lifetime of the acquisition URL?

Dave

[Hadrien Gardeur]

1. Is the assumption that the document is immediately available for download? In our case, we custom prepare each ebook for each customer, so there's sometimes a delay.

We have no such assumptions during the transaction, but once the client gets a callback it is expected to work immediately. In your case, it would be best to delay the user before the callback.

 

2. What is the assumed lifetime of the acquisition URL?

I don't think that we'll give hard constraints about the lifetime of the acquisition URL but it should be sufficiently long enough to download without any trouble (an hour ?).

Hadrien

[Hadrien Gardeur]

There's a typo in my example, no need to include opds://acquire/ in the callback for the Web App: http://www.opds-app.com/?callback=www.feedbooks.com/item/53936.atom?hash=66466884463897923

I also wonder if it's really necessary to append "acquire" after opds://. I know that Bluefire does something like that to separate different kind of interactions but it could be just as easy to simple use opds:// parse the URL and see if it's a feed or an entry. Any thoughts about this Tim ?

Hadrien

[xq.gzh]

in native apps, if user deleted the local books, how can he/she
download the book again?

On Aug 12, 10:39 pm, Hadrien Gardeur <hadrien.gard...@feedbooks.com>
wrote:

> There's a typo in my example, no need to include opds://acquire/ in the

> callback for the Web App:http://www.opds-app.com/?callback=www.feedbooks.com/item/53936.atom?h...

[Benoît Larroque]

They should be in their bookshelf which could be resynchronized

[Hadrien Gardeur]

in native apps,  if user deleted the local books,  how can he/she
download the book again?

Each catalog can provide a shelf where the user can download their books again. You can include such shelf:

• in every feed as a link (<link rel="http://opds-spec.org/shelf" type="application/atom+xml;profile=opds-catalog" href="/user/bookshelf.atom" />)
• as a link in a callback
• in your navigation feeds

Hadrien

[xq gzh]

thanks for  Benoît Larroque and Hadrien Gardeur 

we designed a shop cart in a client, when user click "buying" button, the selected book will add into the cart,  so user can buy many books at one times.

as you know, the payment tools count the proportion of commission by each orders. if one book per order, we will lost many money...

sorry for my pool english again.

2011/8/14 Hadrien Gardeur <hadrien...@feedbooks.com>

--

[Hadrien Gardeur]

I've wrapped up a first version of a draft for OPDS Callbacks at: http://code.google.com/p/openpub/wiki/CallbackSpecDraft

This is still a little rough and will need to be fleshed out a little more but it includes all the new terminology, core definitions and examples to define and understand OPDS Callbacks.

As usual, any feedback is welcome.

Hadrien