Annotation
The aim of this section is to guide the partner through the integration of their publishing platform with Hypothes.is and the CrossRef Event Data API, which is the first step in order to get their data (and annotation) ingested into the HIRMEOS Metrics service(s).
The Hypothes.is integration
A couple of quick remarks from the backend perspective:
- annotations are saved and stored in the Hypothes.is services
- annotations are associated with the URL of the page
CDN
Ubiquity Press has set up a CDN serving all the required libraries, except the Hypothes.is library. A quick overview of the reasons to have libraries served by a CDN:
- all the required libraries are available from the same resource
- all the required libraries are tied to a specific version of the bundle (see more below) and can be upgraded altogether, changing the version in the URL
- the CDN manager (Ubiquity Press) will take care of creating new bundles when the libraries are upgraded, and this will happen consistently with the developments in the libraries and the related platforms (Hypothes.is)
The CDN folders are structure as follows:
https://storage.googleapis.com/operas/<version>/<name>
Where:
version
: version of the JS bundle, (e.g. v1
, v2
)
name
: name of the library
The following table contains a list of the available libraries:
library | public link |
---|---|
epub.js | https://storage.googleapis.com/operas/v1/epub.js |
epub.min.js | https://storage.googleapis.com/operas/v1/epub.min.js |
pdf.js | https://storage.googleapis.com/operas/v1/pdf.js |
pdf.worker.js | https://storage.googleapis.com/operas/v1/pdf.worker.js |
HTML
The best and up to date resource to learn how to set up Hypothes.is annotations on an HTML page is the Hypothes.is Quickstart guide.
EPUB
At the most basic level, the only resources required to enable annotations on an EPUB are the Hypothes.is CDN, jszip
3.1.5
and epub.js 0.3.66
:
<script src="https://cdn.hypothes.is/hypothesis"></script>
<script src="https://storage.googleapis.com/operas/v1/jszip.min.js"></script>
<script src="https://storage.googleapis.com/operas/v1/epub.min.js"></script>
This link hosted by Hypothes.is contains a working implementation. In the example, a function in reader.js
is called
when loading the page. This function initialises an epub.js reader and enables Hypothes.is annotation throughout the
page, including within the EPUB content. The code for this working implementation can be found in
this git repository.
TBC
Embed Dublin Core
It is clear that in order to make easier to calculate metrics around published content, we need to associate the annotations with a unique identifier for the published content, most often the DOI.
The CrossRef Event Data service scans known websites in order to retrieve URLs for the content and associate them with DOIs. To make this happen, the content page should contain Dublin Core Meta tags.
Something similar to the following code snippet should be used in order to allow the CrossRef Event Data service to associate a published content page with a DOI:
<head>
<meta name="dc.identifier" content="10.1371/journal.pone.0160617"/>
</head>
The Event Data documentation has a dedicated section on the best practices for publishers.
Check the HIRMEOS Metrics API
What happens next: - CrossRef Event Data will crawl the pages for annotations - the HIRMEOS Metrics service will gather information on the Event Data API
The results are available on the HIRMEOS metrics, by source:
https://metrics-api.operas-eu.org/events?filter=work_uri:info:doi:10.5334/bbc,measure_uri:https://metrics.operas-eu.org/hypothesis/annotations/v1