Create an easy way to add an OPDS feed to reading apps

[llemeurfr]

Currently, the addition of an OPDs feed is tedious and for geeks only: one has to know the URL of an OPDS feed, copy/paste it, name it manually and validate.

The new use case is:

• A user has an app installed (desktop or mobile), which is compliant with the technique we'll specify here.
• A bookseller or public library adds a button to its website, labelled as "Add this catalog to your reading app" or equivalent.
• The user clicks on the button provided on the website.
• The reading app is automatically triggered, it catches the URL and name of the OPDS feed, automatically adds it to the list of feeds, opens the catalog.

This can be achieved via what is called "OPDS callback", with a button attached to a URL of type opds://. This scheme has been used before, but it seems an innovative way to use it.

The same technique can be used in the scope of a OPDS "catalogs" feed, i.e. a list of OPDS feeds in which a user can choose one or more feeds to add to the app.

It would be great to write a specification (some will call it best practice document) defining how website developers on one side, reading app developers on the other side, should integrate such an affordance.

How should we express this in technical terms?

[HadrienGardeur]

For those who haven't seen it before, the concept of OPDS callback is illustrated in details on the opds.io website at https://opds.io/callback.html

The OPDS URI scheme has been used by multiple reading apps for a while now. This includes:

• Aldiko
• Bookari
• FBReader

In Aldiko, we implemented two different behaviours:

• if you link to a feed, the catalog is added to your list of catalogs and we open the catalog as well
• if you link to a publication/entry that contains a generic acquisition link, we attempt to import the file to your bookshelf

It's worth pointing out though that Apple's inability to support multiple apps for the same URI scheme is problematic on iOS/iPadOS. In some versions it opens the first app installed, in others it opens the last app installed.

The same technique can be used in the scope of a OPDS "catalogs" feed, i.e. a list of OPDS feeds in which a user can choose one or more feeds to add to the app.

I don't think that's necessary, using a rel value such as http://opds-spec.org/catalog would IMO be a better approach for that.

[HadrienGardeur]

This is also related to #16

[llemeurfr]

I don't think that's necessary, using a rel value such as http://opds-spec.org/catalog would IMO be a better approach for that.

We're confronted with this issue in edrlab/thorium-reader#1336 (comment) and I would like to continue this discussion. If there was a way to notify Thorium that it must open its "OPDS feed picker" when a user clicks on some affordance (link/button) on a website, we would have a user friendly solution.

[mickael-menu]

A less geeky approach which would complement OPDS callbacks and is underused by OPDS clients is to auto-discover feeds from any webpage.

For example, feedbooks.com exposes:

<link rel="related" type="application/atom+xml;profile=opds-catalog;kind=navigation" title="Feedbooks" href="/catalog.atom" />
<link rel="http://opds-spec.org/shelf" type="application/atom+xml;profile=opds-catalog;kind=acquisition" href="/user/bookshelf.atom" />

We can let users choose one or more OPDS catalogs to add from the discovered <link> elements, and the title attribute could be used to pre-enter the catalog title. Most RSS readers are doing just that when adding a website.

I haven't seen this used for OPDS 2 though, I don't know why?

[llemeurfr]

But this link is in a Web page. Thorium does not navigate this Web page, the user does. And he is using his web browser for that.
Which user story do you imagine, using these links?
Note also that the context of my question is how to point Thorium at a list of OPDS feeds (a "catalogs" structure) by which the Thorium user will be able to pick some OPDS feeds and add them to his Thorium settings.

[mickael-menu]

This does not answer exactly Thorium's use case but I thought it was interesting in the broader discussion of making it easier to add OPDS feeds to reading apps.

The user story for these links is pretty similar to adding a new blog to a RSS reader, for example:

---

As an online library patron, I want to add my library bookshelf to my reading app to easily download my borrowed books. To do so, I'll either:

• Type the library website domain into the app (e.g. bibliotheques.paris.fr)
• Copy the current URL of the library website into the app

The reading app will show me a list of feeds for this library auto-discovered from the address. For example: My bookshelf, Recent acquisitions, Library catalog, etc. I can add one or more catalogs to the app from the list.

---

I don't think this as an alternative to the OPDS callback but in addition, both would be useful. The OPDS callback has some downsides like OS limitations (only one app can answer the scheme on iOS) and the user needs to locate the button on the website.

I'm not commenting specifically on the catalog registry, as both techniques would work well with either a single feed or a registry.

[HadrienGardeur]

This discussion is frankly confusing because multiple concepts are mixed together.

I've seen three different things mentioned at least :

• a catalog registry
• auto discovery on a webpage
• callbacks

---

A catalog registry is a full catalog, that would contain:

• one or more navigation feed, to organize your registry (browse by country or region/province/state in Aldiko's registry)
• one or more "catalogs" feed that reference OPDS catalogs that you can add to your app
• a search endpoint
• a geolocation endpoint (show me libraries near me)

There's absolutely no need to reinvent the wheel for navigation feeds or the search endpoint.

What we would need to define are limited to:

• a new catalogs collection role and the metadata associated to such catalogs
• a new URI template for the geolocation endpoint

I don't think that the main OPDS 2.0 specification is a good fit for this, a separate document would be much more suited.

---

Auto-discovery on a webpage is what @mickael-menu was talking about and is mostly useful if you can provide a contextual action while browsing.

In practice, this is not really useful for reading apps as they don't have the ability to provide such contextual actions in Chrome/Safari/Firefox without installing a browser extension.

If the reading app provides the ability for the user to type their own URL, this could be useful to detect a catalog :

• user types https://banq.qc.ca/accueil/
• the reading app detects the presence of an OPDS catalog at https://banq.pretnumerique.ca/v1/home.opds2
• the reading app asks the user if they'd prefer using the website or the catalog

---

Finally a callback based on a URI scheme is mostly useful to facilitates the transition between a website and a reading app.

The three main use cases are:

• adding a catalog
• completing an authentication
• or fulfilling a transaction

Adding a catalog is pretty straightforward. Let's use BANQ as an example once again. On their website, they could easily display a button to "Add a catalog" where the URL is opds://banq.pretnumerique.ca/v1/home.opds2.
When you click/tap on this button, your OS provides a list of compatible apps. Select your preferred app and the catalogs gets added to that app.

Completing an authentication is something covered in Authentication for OPDS, so I won't discuss it in details here. This is mostly handled inside an app, using a webview.

Finally, fulfillling a transaction is very similar to adding a catalog. The only difference is that instead of adding a catalog to a reading app, you end up downloading a publication instead.

As @mickael-menu has pointed out, URI schemes are less reliable on iOS/iPadOS than on other operating systems.