Intro to Exporting iBooks Widgets

Exporting & Previewing iBooks
1

This article is about iBooks Author, which is no longer supported by Apple. Read our blog post here: Transition from iBooks Author & Supporting Embedding HTML5 Animations in Digital Books – Tumult Company Blog

If you're looking to get Hype content into an Epub, here's some solutions:

Posted August, 2018:

New to the idea of HTML widgets in iBooks Author? Watch this video:

hype-widget.jpg746×429 77.5 KB

Are you ready for the advanced stuff? Visit this thread.

To export your Tumult Hype document as a .wdgt file to drop into iBooks:

  1. When building your document, select a size from the Document Inspector's 'document size' dropdown (view options below).
  2. When you're finished, select File > Export > Dashboard / iBooks Author Widget
  3. This produces a .wdgt file which you can drag directly into iBooks Author.

The 'Standard' sizes allow room for a title and caption above and below your widget. The Full screen sizes cover the entire available area of the iPad.

Choosing a size

The preset sizes are as follows:

If you create a widget at a small size (around 400x400) and display it within your book at that resolution, the widget can play inline by tapping once on the widget. Large widgets will expand to fill the screen.

A Crash course in iBook Widgets

  • Here is Apple's page on iBook widgets: Create HTML5 widgets for iBooks Author - Apple Support which explains many of the notes below.
  • In the above link, you'll find a reference to reducing a white flash — Tumult Hype has built in support for suppressing this flash during widget load.
  • Audio in iBooks follows the same requirements as audio in Mobile Safari. If you want audio or video to play automatically, you'll need to do it in response to a user action (like tapping a button). 'On Scene Load' or Timeline actions will not play audio.
  • Use the .m4a format (AAC) for your audio. Otherwise, you will receive an error in iTunes Connect during widget upload. xAct is a great tool for quickly converting files. This post recommends removing file extensions from your audio files. Try this out if you're having issues playing audio.
  • There will always be a 'X' or 'Done' symbol in the upper left hand corner. This is used to close the widget and might affect your design. Here's a template to see where the interface element might hit your design.
  • If you are building a flexible-layout book, make sure you set your widget to be 'anchored' using the object placement settings.
  • The widget thumbnail is generated based on the position of the playhead when you select File > Export as HTML5 > iBooks Widget.
  • The pinch gesture on the HTML widget closes the widget, but there's a way to workaround this behavior.
  • The background of the HTML widget area is white by default, and cannot be transparent (there isn't a way to see your book underneath the widget, though this would be nice).
  • Since all content is loaded locally, there's no need to use Offline Application Cache.
  • Web fonts and external videos like Youtube embeds will work, but this requires that your readers are online. When defining your fonts, use multiple font families to ensure there's a pleasant-looking fallback: font-family: "My Custom Font",Helvetica, Arial, sans-serif;
  • Embedding a Youtube video? Use a regular rectangle, and copy + paste the youtube iframe code within that rectangle. iBooks for Mac does not like an HTML widget containing an Iframe. Double iframe = bad.
  • Use retina-quality images whenever possible. Please note that you can make your document size 1024x768 and still see retina quality images as long as the images you drop into Hype are retina-ready. (More info)
  • Supporting the iPad Pro? 1024x768 will likely show the HTML widget in full-screen.

Known issues and how to avoid them:

  • Experiencing flashing during scene transitions? You may want to place an object behind all other objects to display during those transitions (a persistent symbol).
  • iOS 11 has new restrictions on external content which causes HTML widgets, external video, and other external content to fail. Read more here.
  • Large images might not display at retina resolution. Make sure your images are under 5 million pixels. You can multiply (the width) X (the height) to get this value. One common fix for fuzzy images is to split large images up into splices and group them in Tumult Hype. This fools the device into thinking that it is loading two separate images (and thus reduces the memory requirements). Older iPads have more trouble with large images.
  • Don’t use any foreign characters, spaces, or punctuation in the names of your files. We’ve discovered this causes issues for playing media. Rename your audio files to be filename.mp3. (More info)
  • We have heard that some MP3s don't play. If this is the case for you, use the M4A format for your audio. And see this.
  • In 'Scroll view' mode, your widget might not display unless you have the widget set as 'anchored'. This applies to flexible-layout books built for iPhone + iPad layouts. More info here.
  • The retina version of Default.png (Default@2x.png) is not loaded by iBooks, but might in the future. Use this automator script to remove it, saving some space in your widget file. This is the thumbnail of the Widget displayed inline in the page. We build that file because we hope someday this is not the case. See this document for Apple's 'Best Practices' regarding that image. We do use that image to reduce the white flash when loading your widget into device memory.
  • If you are working with forms somewhere in your HTML widget, set contenteditable="true" on your input forms. Otherwise, iBooks won't let your users type within the forms.
  • Your widget may resize when clicking a link in your widget which takes you outside of your book (into Mobile Safari, for example)
  • Unfortunately it's not possible to drop a large Widget into your book and have it play automatically. This works as expected.

Please note that many of the above issues will likely be fixed. If they are, please let me know so I can remove them! Onward and upward.

Potentially resolved issues:

The issues below have not recurred and may have been resolved:

  • Audio in large iBooks sometimes does not play. Documents below 100 megabytes in size generally have no issues. For more info, read this thread on the iBooks support forum. Audio in general is not reliable, and may cause reduced framerates, or simply not work. If you have any issues with iBook audio, please let us know and we'll do our best to help. Unchecking 'preload' in the resource library for all audio files will reduce the amount of memory required and sometimes resolves problems.

Placement Issues viewing in 'Scroll View' mode?

When dropping your widget into an iBook built for an iPhone and iPad-compatible book, we currently recommend dropping the widget into a text object that is included on the original template layout. Simply drop the widget into that text object with the Anchored option selected in the Inspector’s Wrap Selector section. You'll notice a blue dot in iBooks Author’s text object when viewing your book in Landscape mode. Dragging the blue dot around the Text Object in Landscape view will affect the placement of the Widget when the iBook is viewed in Scroll View mode as well. The image below shows the blue dot and the 'anchor' object placement setting:

Read on!

1 Like
6

My large widgets do play automatically, so this must have been fixed.

Thanks,
Brian

1 Like
7

I appreciate that! Updated above.

8

@Daniel Very helpful… You’re the best. :smiley:

1 Like