Introduction
The next time you say, "I am making the best decision based on the information I have available to me.", you want to know your decision was made with a clear perspective and informed by the bigger picture. Today more than ever, students are presented with an increasing number of tools and study aids, each producing valuable learning data. As educators look to improve student success through the analysis of this data, the difficulty of gathering and consistently interpreting the data is compounded by the number of tools in play.
As the world’s leading eTextbook platform, we understand the value of analyzing how students interact with their course materials. We also know the complexity and difficulty involved when analyzing this data in context with data produced from other learning platforms. For this reason, we are pleased to provide standards-based data feeds to our partners.
Now you will have the most up-to-date learning data produced by your learners on the VitalSource platform. As students interact with their course materials, VitalSource will either push the data from each interaction to you in near real-time or extract the data for periodic pickup. Using this information, you will be able to customize your student portal, deliver interventions based on recent behavior, power research projects or simply see if students have completed a reading assignment before class.
Data Universe
Data feeds are available to both institutions and publishers. Institutions or other parties that provision content directly to users will receive all the learning events from their users. Publishers or parties that create content will receive de-identified event data generated by all users who interact with their published content. In all cases, data availability is limited by the VitalSource privacy policy and any user or partner-level privacy settings.
Delivery Frequency
VitalSource has two options for delivery: near real-time and periodic delivery. Keep reading for a summary of each delivery option as well as the key benefits of each. 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.
Engagement Event Types
View Event
View events are recorded when an end user views a page within an asset. For PDFs, view events are recorded for each page. View events are triggered on epub content when the user interacts with a section of content identified by page labels. While configurable on custom instances of Bookshelf, by default, view events are only triggered with the user remains on a given page for at least 3 seconds.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Page | For PDFs, this is the page index within the content. For epubs, this is the page label from the page that the user viewed. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
Print Event
Print events are recorded when the user prints a page of content.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Pages | An array of pages that were printed. For PDFs, this is the page index within the content. For epubs, this is the page label from the page that the user viewed. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
Download Event
Download events are recorded when the user downloads a copy of the asset for offline access.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
Search Event
Search events are recorded when users search for a term within the content.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Search Term | The term that the user searched. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
Highlight Event
Highlight events are recorded when users highlight passages within the content. Epub highlights are communicated as a CFI range. PDF highlights are represented by a series of coordinates.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
| Annotation GUID | Unique identifier for the annotation. |
| Has Note | Boolean indicating if the user entered a note on the highlight annotation. |
| VBID | The unique identifier for the book. |
| Content Type | The type of content that was annotated: epub, pdf. |
| Highlighter ID | Unique identifier for the highlighter. |
| Chapter | The chapter label of the chapter containing the annotation. If a highlight spans multiple chapters, only the first chapter is included. |
| Page | For PDFs, this is the page index within the content. For epubs, this is the page label from the page that the user viewed. |
| CFI Range | For epubs, the CFI range of the selection. |
| Start Position | For PDFs, an integer representing the starting character offset from the start of the page. Most likely 0 for bookmarks. |
| Length | For PDFs, an integer representing the length of the selection. Omitted for bookmarks. |
| Start X | For PDFs, the starting X coordinate of the selection. |
| Start Y | For PDFs, the starting Y coordinate of the selection. |
| End X | For PDFs, the ending X coordinate of the selection. |
| End Y | For PDFs, the ending Y coordinate of the selection. |
| Text | The text that was selected by the user. Only available to content creators. |
| Created At | The timestamp from when annotation was created in UTC. |
| Updated At | The timestamp of the last update to the annotation in UTC. |
Note Event
Note events are recorded when users enter notes on a highlight annotation. Notes are identified by the Has Note attribute.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset. |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
| Annotation GUID | Unique identifier for the annotation. |
| Has Note | Boolean indicating if the user entered a note on the highlight annotation. |
| VBID | The unique identifier for the book. |
| Content Type | The type of content that was annotated: epub, pdf. |
| Highlighter ID | Unique identifier for the highlighter. |
| Chapter | The chapter label of the chapter containing the annotation. If a highlight spans multiple chapters, only the first chapter is included. |
| Page | For PDFs, this is the page index within the content. For epubs, this is the page label from the page that the user viewed. |
| CFI Range | For epubs, the CFI range of the selection. |
| Start Position | For PDFs, an integer representing the starting character offset from the start of the page. Most likely 0 for bookmarks. |
| Length | For PDFs, an integer representing the length of the selection. Omitted for bookmarks. |
| Start X | For PDFs, the starting X coordinate of the selection. |
| Start Y | For PDFs, the starting Y coordinate of the selection. |
| End X | For PDFs, the ending X coordinate of the selection. |
| End Y | For PDFs, the ending Y coordinate of the selection. |
| Text | The text that was selected by the user. Only available to content creators. |
| Created At | The timestamp from when annotation was created in UTC. |
| Updated At | The timestamp of the last update to the annotation in UTC. |
Bookmark Event
Bookmark events are recorded when users create a bookmark within the content. Bookmarks share a payload structure with notes and highlights, but have no selected text.
| Attribute | Description |
|---|---|
| Timestamp | The time at which the end user viewed the page. |
| User | The user who is interacting with the asset |
| Asset | The piece of content in which the user is interacting. This is often a book. |
| Session Identifier | A unique session identifier that is updated each time the user closes and opens the reading application. |
| Annotation GUID | Unique identifier for the annotation. |
| Has Note | Boolean indicating if the user entered a note on the highlight annotation. |
| VBID | The unique identifier for the book. |
| Content Type | The type of content that was annotated: epub, pdf. |
| Highlighter ID | Unique identifier for the highlighter. |
| Chapter | The chapter label of the chapter containing the annotation. If a highlight spans multiple chapters, only the first chapter is included. |
| Page | For PDFs, this is the page index within the content. For epubs, this is the page label from the page that the user viewed. |
| CFI Range | For epubs, the CFI range of the selection. |
| Start Position | For PDFs, an integer representing the starting character offset from the start of the page. Most likely 0 for bookmarks. |
| Length | For PDFs, an integer representing the length of the selection. Omitted for bookmarks. |
| Start X | For PDFs, the starting X coordinate of the selection. |
| Start Y | For PDFs, the starting Y coordinate of the selection. |
| End X | For PDFs, the ending X coordinate of the selection. |
| End Y | For PDFs, the ending Y coordinate of the selection. |
| Created At | The timestamp from when annotation was created in UTC. |
| Updated At | The timestamp of the last update to the annotation in UTC. |
Dereferencing APIs
Many of the contextual attributes in the VitalSource data feeds are transmitted as Internationalized Resource Identifiers (IRIs). An IRI is simply a unique reference to an object. While some of IRIs included in Caliper events should be treated as simple identifiers, others can be dereferenced for more information. Below is a list of the IRIs that can be dereferenced by accessing the IRI over HTTPS.
Please note that you are only permitted to see user data for your own organization. If your data feed includes de-identified data, you will not be able to dereference any user attributes.
"id": "https://api.vitalsource.com/v4/users/ABCDEFGHIJKLMNOP",
"type": "Person"
"id": "https://api.vitalsource.com/v4/books/9780000000000",
"type": "DigitalResource"
Annotation
"id": "https://notes.vitalbook.com/v2/highlights/ABCDEFGHIJKLMNOP", "type":"HighlightAnnotation"
Comments
Article is closed for comments.