Near Real-Time Delivery

VitalSource has two options for engagement data delivery: near real-time and periodic delivery.  Delivery frequency doesn’t limit the scope of data you’ll receive in your data feed, only the frequency at which you receive your data.

Near Real-time Delivery

As users engage with content, VitalSource will post engagement events to an endpoint you create and host as soon as possible.  This near real-time delivery supports the greatest variety of use cases.  With the most frequently delivered engagement data, what will you build?

• More integrated user experiences: Incorporate student learning interactions within your tool or platform for a more integrated user experience.
• More Relevant Interactions: Customer user interactions within your platform with the most up to date engagement data.

Not interested in near real-time delivery?  Check out daily or weekly periodic delivery.

IMS Caliper 1.1 Formatting

As a contributor to the IMS Caliper standard, VitalSource is pleased to support the formatting of engagement data using Caliper 1.1.  Caliper differentiates itself as a standard by prescribing both a data model and semantic model for communicating learning activities.

• Industry Standard: Created by IMS, Caliper is the industry standard for transmitting learning interactions.
• Powerful Foundation: Based on JSON-LD, Caliper is both human readable and easily understood by machines.
• Semantic Interoperability: Caliper prescribes a vocabulary for communicating learning interactions, ensuring consistent interpretation across systems.
• System Interoperability: Caliper defines the structure of each data point, ensuring consistent integration and consumption across systems. 

Caliper Context Extension

Caliper JSON-LD documents define a context, denoted by the @context keyword, a property employed to map document terms to IRIs to one or more published vocabularies. Inclusion of a JSON-LD context provides an economical way for Caliper to communicate document semantics to services interested in consuming Caliper event data.

On certain events, VitalSource has extended the IMS Caliper specification by providing an additional context definition.  This extension of the context allows for the inclusion of additional event types that are not currently described in the Caliper standard.  The Caliper standard allows for this extension and may ultimately adopt the VitalSource-described events in a future release of the Caliper standard.  Extended events are clearly identifiable by inspecting the context attribute.  These events will include both the Caliper context and the VitalSource context.

Receiver Requirements for Near Real-Time Delivery

Messages will be transmitted to the receiving endpoint via a HTTP POST.  The receiving endpoint must conform to the standards below.

Persistence

• Once a message is confirmed by the receiving endpoint, it will no longer be available for resubmission.
• Messages will be queued by VitalSource for 7 days from the time of the event.  Messages that are not successfully received during this time will be discarded.
• Only data generated after confirming the integration will be sent.  Backfilling historical data is not currently supported via this mechanism.

Transmission

• Our goal is to transmit events as fast as possible, but we cannot guarantee the latency of the data feed.
• While infrequent, duplicate transmission of event data is possible.  Receiving clients should expect messages to be delivered at least once.  Identifiers included in each event can be used to eliminate duplicate events.

Response Codes

Backoff Process

Resending of event messages is governed by a backoff process.  As transmission failures occur, each failure delays the sending of additional events by one minute with a maximum delay of 5 minutes.  This delay remains in effect until the first successful transmission.

Near Real-Time Example Submission

Caliper-formatted learning events are gathered by VitalSource and transmitted your endpoint via HTTP post.  Below is an example payload that would be sent to your receiving endpoint.  Walking through the request payload, you’ll notice that learning events are transmitted within a Caliper envelope.  Top level envelope attributes include a reference to VitalSource as the “sensor” responsible for collecting and transmitting the learning events, a timestamp for submission and the dataVersion indicating the version of Caliper used to format the events.

This example includes two learning events from the same user, https://api.vitalsource.com/v4/users/WE6A2GMSJ6NMNGT2RMJH.  The first event records the user reading page 158 in the book, https://api.vitalsource.com/v4/books/9781118654477.  The second event records the user reading page 102 in the book, https://api.vitalsource.com/v4/books/0-323-01096-2.

Request Headers

X-VitalSource-API-Key: ABCDEFGHIJKLMNOP
Content-Type: application/json
Accept: application/json

Request Payload

{
 "sensor": "https://bookshelf.vitalsource.com",
 "sendTime": "2017-04-25T18:02:58.305767447Z",
 "dataVersion": "http://purl.imsglobal.org/ctx/caliper/v1p1",
 "data": [
  {
   "@context": "http://purl.imsglobal.org/ctx/caliper/v1p1",
   "action": "http://purl.imsglobal.org/vocab/caliper/v1/action#Viewed",
   "actor": {
    "id": "https://api.vitalsource.com/v4/users/WE6A2GMSJ6NMNGT2RMJH",
    "type": "Person"
   },
   "edApp": {
    "id": "https://bookshelf.vitalsource.com",
    "type": "SoftwareApplication"
   },
   "eventTime": "2017-04-25T18:02:54Z",
   "object": {
    "id": "https://api.vitalsource.com/v4/books/9781118654477/158",
    "isPartOf": {
     "id": "https://api.vitalsource.com/v4/books/9781118654477",
     "type": "DigitalResource"
    },
    "name": "158",
    "type": "Page"
   },
   "session": {
    "id": "https://api.vitalsource.com/v4/sessions/2a5a3fe515d2c55d29303fd208084980",
    "type": "Session"
   },
   "type": "ViewEvent",
   "uuid": "7b0dc5d5-465f-5aca-850a-0f713d0bd15b"
  },
  {
   "@context": "http://purl.imsglobal.org/ctx/caliper/v1p1",
   "action": "http://purl.imsglobal.org/vocab/caliper/v1/action#Viewed",
   "actor": {
    "id": "https://api.vitalsource.com/v4/users/WE6A2GMSJ6NMNGT2RMJH",
    "type": "Person"
   },
   "edApp": {
    "id": "https://bookshelf.vitalsource.com",
    "type": "SoftwareApplication"
   },
   "eventTime": "2017-04-25T19:02:40Z",
   "object": {
    "id": "https://api.vitalsource.com/v4/books/0-323-01096-2/102",
    "isPartOf": {
     "id": "https://api.vitalsource.com/v4/books/0-323-01096-2",
     "type": "DigitalResource"
    },
    "name": "102",
    "type": "Page"
   },
   "session": {
    "id": "https://api.vitalsource.com/v4/sessions/2a5a3fe515d2c55d29303fd208084980",
    "type": "Session"
   },
   "type": "ViewEvent",
   "uuid": "c6819c04-2a17-524f-838e-7412500b6c24"
  }
 ]
}