Safari Documentation
Interactivity on Safari
This chapter describes the features available for integrating multimedia elements into Safari titles, and explains the steps involved. Linking to media directly from the book’s page provides a much more seamless, intuitive user experience than requiring users to check the Extras tab for supplemental content. There is no disruption to the reading experience. Imagine you’re reading a book on Safari and you notice a clickable icon on the page that, when clicked, pops up…
- a video illustrating the how-to steps just discussed.
- an interactive quiz to help you assess what you’ve learned so far.
- a compiled application of the source code you just skimmed.
This chapter explains what is supported on Safari today and includes instructions for implementation.
Supported Media Types
The most common enhancement to an ebook is video, and embedding clips from the Safari CDN (content delivery network) has several benefits: you’ll leverage the streaming capabilities of the CDN, you’ll have access to usage reporting, and you’ll earn usage credit for publisher payment calculations. We also support quizzes or assessments: 1) via HTML5 content in a book’s source EPUB file, 2) as standalone downloadable files on the Safari Extras tab, or 3) via links to externally hosted exams. You can also add links to just about any type of content that’s hosted elsewhere (via URLs), including exams, exercises, or podcasts. For now, if you want to incorporate a podcast or other sound files to your pages via inline links, you can convert your sound files to MP4 format and follow the process for incorporating inline links to video.
Video
User Experience
As a user reads the book pages on Safari, she sees a publisher-defined clickable area on the page, as well as a Safari icon in the right margin. She clicks one or the other, and the video clip pops up in a separate, standalone player window and begins to play.
(See https://ssl.safaribooksonline.com/9780789745095/17 for a live example.)
Considerations for Inline Links to Video Clips
Part of the process of adding inline links to video clips is to create a separate video title on Safari in which the clips reside. The creation of a separate video title is necessary for two reasons: 1) For generating usage data and publisher payments based on minutes viewed, and 2) It leverages the Safari video CDN to serve the appropriate streaming format in an appropriately-sized standalone player window.
However, you don’t have to offer the video title as a standalone product on Safari – you can choose to “hide” it, as described in Extras Video vs. Hidden Video. We recommend taking advantage of the “hide” feature whenever appropriate, because these supplemental video fragments can be confusing when discovered out of context via search or browse.
Implementing Inline Links to Video
1) For book/video pairings, use the dependencies element in the book metadata to lists the associated video title(s). This metadata ensures that if the book is on a user’s bookshelf, they will have access to all of the content of the video without having the video title on their bookshelf.
<dependencies>
<dependency fpid="vvvvvvvvvvvv" />
</dependencies>
where vvvvvvvvvvvv is the FPID of the video. Only the video FPID appears here, not the individual clips.
2) Embedded links (inline links):
Link to video clip in EPUB:
https://ssl.safaribooksonline.com/vvvvvvvvvvvv/ccccc
Link to video clip in PDF:
/getinlinevideo?referrerid=xxxxxxxxxxxx&id=vvvvvvvvvvvv/ccccc
Link to video clip in Docbook XML (for legacy titles):
<ulink type="video" url="/getinlinevideo?referrerid=xxxxxxxxxxxx&id=vvvvvvvvvvvv/ccccc">the text to display</ulink>
Where
xxxxxxxxxxxx is the fpid of the book
vvvvvvvvvvvv is the fpid of the video
ccccc is the id of the clip
3) The video clips do not have to be referenced in the Extras metadata (<relatedfiles>). But if you want to display a link to a video clip in the Extras tab, you can add:
<relatedfiles display="on">
<filegroup>
<description>
<para>Descriptive text ...</para>
</description>
<ulink type="video" url="/getinlinevideo?referrerid=xxxxxxxxxxxx&id=vvvvvvvvvvvv/ccccc">the text to display</ulink >
</filegroup>
</relatedfiles>
NOTE: The getinlinevideo URL reference above will work if xxxxxxxxxxxx is on the current user’s bookshelf and the book’s metadata lists vvvvvvvvvvvv as a dependency.
NOTE: If a bookshelf user navigates to the video directly (instead of using the book’s links) they will not be able to view the clips unless they have added the video to their bookshelf.
Extras Video vs. Hidden Video
You can make video clips available on your book’s Extras tab on Safari, by uploading the video clips to Safari’s secure Extras server and including <relatedfiles> metadata to link to the files as you would any other Extras file. However, Extras video clips do not generate usage data or publisher payments, and inline links to Extras video clips are not supported.
Hidden video titles make it possible for publishers to upload video for use only in the context of a book. This video content will be available only from a book's Extras tab and/or from inline links in the content of the book. Although you’re actually creating a standalone video title in this scenario, it will not be discoverable as a standalone product with its own catalog page. Hidden video is:
- Hidden from search.
- Lacks a catalog page (can't find by putting in a catalog page URL).
- Hidden from category browse (even if the video is assigned to categories).
The video title is still a separate product with an FPID, and is still eligible for payments. The files and process required for publishers to upload a video is the same as in Implementing Inline Links to Video. The video title otherwise functions as all other Safari-hosted video, including using our player, with usage data available to BO Reporting and Publisher Payment Reporting.
To implement this feature, create a standard Safari video title, making sure to include the metadata in the related book’s metadata, as described in Implementing Inline Links to Video. Then simply include this additional element in the video title’s metadata:
<hidden/>
Then set up the inline links in the book content as described in Implementing Inline Links to Video. If you also want to include links to the clips on the book’s Extras tab (while retaining reporting and revenue features), set up the book’s <relatedfiles/> metadata as described in Implementing Inline Links to Video.
Note that even hidden video titles need all the required elements in metadata.xml (per safarimeta.dtd) such as publishername, author, and pubdate. Even though no one can view the catalog page, required fields are still validated upon upload and are also used for reporting.
Assessments, Exams, and Exercises
You can add assessments, exams, or exercises in three different ways. 1) In EPUB, use HTML5 to add the assessment directly to the pages. 2) In PDF, add a special Web link to point to an assessment hosted on Safari’s Extras server. 3) In Docbook, add a ulink to link to an assessment hosted on Safari’s Extras server. Each of these options are described in more detail in the upcoming sections.
HTML5 Assessment, Exam, or Exercise Within the Book’s Content
With the release of the EPUB 3 specification, HTML5 support is officially part of the EPUB standard, and Safari already supports EPUBs that include rich media and interactivity, including quizzess, assessments, exams, or exercises. Keep in mind that not all browsers support all features of HTML5, so we recommend using fallbacks whenever possible. The O’Reilly title HTML5 for Publishers provides excellent examples of how to use HTML5 in an EPUB. For one example of this in action in this book, click here and scroll down to the “test out the finger painting example here” link, just above Figure 1.5. (See the following screen capture of the finger painting example.)
Linking to Externally Hosted Content
You can add links in your book content on Safari (whether the book was created from EPUB, PDF, or legacy Docbook source files) to any externally hosted content, including exercises, exams, or assessments, via regular Web links. As a user reads the book pages on Safari, he sees an icon or other indicator that the content is clickable.
(A live example is available at https://ssl.safaribooksonline.com/9781449379827/9.) He clicks the publisher-defined link area on the page—and a separate browser window pops up and displays the externally hosted content.
Exams as Safari Extras
An <exams/> metadata element is available to provide usage tracking and compensation to publishers for including practice exams with their books as Extras. The system populates SBO’s usage tracking royalty database for the parent book the first time a user clicks on the link to access a practice exam. A click on the link (regardless of whether the link initiated a download or took the user to a hosted exam site, and regardless of any interaction with the exam) triggers page view credits in proportion to the number of questions in the exam. See the next page for implementation instructions.
Here’s an example of how to set up the <exams> metadata element:
<exams>
<exam id="exam_1" question_count="5"/>
<exam id="exam_2" question_count="3"/>
</exams>
Set up Extras metadata for a Safari-hosted, downloadable exam:
Add the type="exam" attribute to the file element, and the xreflabel attribute identifying the ID of the exam.
<relatedfiles display="on">
<filegroup>
<file type="exam" id="examid" xreflabel="exam_1" url="/FPID/filename.ext" format="formattype" size="integer"/>
</filegroup>
</relatedfiles>
Add an inline link within a book to an exam on the Extras tab in PDF or Docbook content:
In a legacy DocBook title, use a regular extras ulink, and add the type="exam" attribute. The fileid points to the extra.
<ulink type="exam" url="/getinlinefile?fileid=FPID/examid">the text to display</ulink>
In a PDF title, add a web link:
/getinlinefile?fileid=/FPID/examid
Set up Extras metadata for externally hosted exams:
For externally hosted exams that don’t require a unique activation code, add the type="exam" attribute to the ulink element, and the xreflabel attribute identifying the ID of the exam.
<relatedfiles>
<filegroup>
<ulink type="exam" xreflabel="exam_2"
url="http://testengine.com/folder/1234567890123.html">Take the quiz for Chapter 4</ulink>
</filegroup>
</relatedfiles>
Add an inline link within a book to an externally hosted exam that is linked on the Extras tab:
In a legacy DocBook title, use a regular extras ulink to an externally hosted exam:
<ulink type="exam" xreflabel="exam_2" url="http://testengine.com/folder/1234567890123.html">Take the quiz for Chapter 4</ulink>
Best Practices for Interactive Elements Displayed on the Extras Tab
To make the interactive elements more discoverable to users, you can also include links on the title’s Extras tab, as shown here:
We recommend organizing your Extras content and providing any information you think the user will find helpful. This will cut down on confusion and support issues. The Safari interface allows you to add descriptions/instructions and to group content as appropriate.
Publisher Payments
How does the compensation for interactive links work? Publishers can raise the MSRP of enhanced products on Safari (within reason), if the content is not available as part of the print “package” (on a DVD, for example). Also, when video clips and links to exams are set up as outlined in this document, usage of that content is included in payment calculations.
Conclusion
If you need further information about file preparation or any of the processes described in this chapter, please email msharp@safaribooksonline.com.