Thursday, December 15, 2011

Creating Custom Sample EPUBs for Apple iBookstore

When readers go the iBookstore and happen upon your book, they can download a sample to get an idea of what your book is like.

Get Sample

The sample file is downloaded to their iPad (or other iOS device) and the prospective customer can read a few pages of your book. When they get to the end of the sample, they are invited to purchase the book:

Buy this book!

Apple will automatically create a sample file from your EPUB when you upload your book, using either the first chapter or 5% of the total word count, whichever is more.

If you'd like to offer some other quantity or selection of sample content, you can create a custom sample EPUB file.

First, make a copy of your final EPUB. You obviously don't want to work on the original! Make sure to delete the .iTunesMetadata.plist file if iTunes has unhelpfully and surreptitiously added it to your file.

Next, decide how much of your book you want to offer as a sample. I like to offer enough of the book to get a taste, but not so much that they don't need to buy my book! :)

Eliminate the files that shouldn't be part of your EPUB. For example, you might delete all of the XHTML files from Chapter 2 onward. If you have particularly long chapters, you might not even want to include the entire first chapter. In that case, eliminate the part of the XHTML file that should not be included in the sample. In this case, make sure that the code in the remaining file still validates (e.g., has all of the appropriate closing tags).

The next step is to go through the XHTML files that will be included and search for IMG to see which image files you'll need to keep. Then go through your OEBPS folder and actually eliminate the image files that are not used in the sample. Repeat this step for any other extra files (audios, video, pdfs) that may not be a part of the sample.

Since you've removed both XHTML files and media files, you'll have to remove their declarations from the <manifest> in the content.opf file. I keep my images folder open, gather the declarations for the "good" images at the top of the manifest, and then delete the rest with one fell swoop.

Don't forget to remove references to the non-included XHTML files in the spine and guide sections.

Next, get rid of all the links that refer to documents not included in the sample. For example, you might have a TOC that links to every chapter in your book.

Here's what the code looks like in my book:

<p class="TOC-Header-3"><a href="EPUBwCS55-body-1.html#toc_marker-2-1-8">Columns</a></p>

And of course, each entry may have a different class, a different destination, and a different title.

I use GREP to quickly remove the links. And the links end up looking like this:

<p class="TOC-Header-3">Columns</p>

You can't have any links to files that are outside of your sample EPUB.

Hmm. Now that I think about it, it makes more sense to make the links remain, but go to the final page. I haven't tested it (and it may be two weeks before my next books is live on the iBookstore), but this is the GREP I will use:

grep link cleaner, absolutely final

(That lovely thing says "find a single link and remember the clickable text and then replace it with a link that goes to the buy button at the end of the book but keep the clickable text the same." Don't you love GREP?)

And here's how my code will look:

<p class="TOC-Header-3"><a href="EPUBwCS55-body-1.html#com_apple_itunes_epub_end0000">Columns</a></p>

Notice that I'm changing all the links from the deleted files to the same target "EPUBwCS55-body-1.html#com_apple_itunes_epub_end0000".

Finally, the hardest part is to adjust the toc.ncx file so that the Table of Contents items in the non-included chapters appear in gray—so the prospective customer knows what will be available in the full book—but don't generate errors in EpubCheck (as the actual links would).

Here's a part of the toc.ncx file from my recently published “From InDesign CS 5.5 to EPUB and Kindle”:

<content src="EPUBwCS55-body-6.html#toc_marker-7-3-1"/>
<content src="EPUBwCS55-body-6.html#toc_marker-7-3-1"/>

But the "EPUBwCS55-body-6.html" document is beyond the scope of the sample. Change it as follows:

<content src="EPUBwCS55-body-1.html#com_apple_itunes_epub_end0001"/>
<content src="EPUBwCS55-body-1.html#com_apple_itunes_epub_end0002"/>

where “EPUBwCS55-body-1.html" is the last available file in your sample EPUB, and “com_apple_itunes_epub_end0000” ends in a unique, sequential number. Start with 0001 and increase by one for each grayed out link.

You'll also, at the end of the final document in your Sample EPUB, have to create a bunch of a tags whose id is equal to each of the com links you created:


Make sure you have as many ids as you do numbered coms in your toc.ncx file.

Any link that has the com_apple_itunes_epub_end0000 link will appear in gray in the navigational TOC.

Gray items in TOC

Once, for Barcelona, Catalonia, by Matthew Tree, I grayed out some interior items because I wanted to include the afterward. It worked fine, though it might feel a little confusing to someone paging through the sample.

I usually have to run EpubCheck about six times to catch all of the missing bits. It probably won't take you as many passes, but I recommend you use it to make sure you've caught all the changes.

Once you've zipped your Sample EPUB up, you can attach it to your ebook in the Assets panel of the iTunes Producer window:

Choose Sample

If you've got any suggestions for how to choose the content for a Sample, I'd love to hear what strategies you've used or considered.


  1. Great post on a topic that we often think about.
    We have taken a different strategy on previews for the time being: we rely on the standard preview provided by each distributor but add in a special call out for customers previewing the guidebook to the first page. In this note we give a link to an enhanced custom preview (PDF format) housed on our website.
    Although not the ideal solution in some ways, this strategy allows us to provide a consistent preview experience across all distributors and engage with our readers. In addition, we're able to update or change previews without affecting customers that have already downloaded a preview.
    We just added this feature in a few re-published guidebooks, and have seen a big uptick in sales as well as an increase in subscriptions to our email list.

  2. Great post. I have been looking for this for a long time. It solves my problem on preparing iBooks previews. I have just revised all my 11 previews.

    Many thanks!


  3. Liz, in a lot of cases, wouldn't it be easier to just export the chapter(s) or pages you want from InDesign? Then you don't have to go through the rigamarole of combing though the image files and manifest and spine and guide to get rid of what you don't want.

    By replacing CSS and toc.ncx files from the full epub to the sample epub (and tweaking the ncx as you describe), I think that'd fix it. If you did a ton of work to the XHTML files too, you could replace the XHTML in your sample epub with the matching XHTML from your full one.

    If you have links in your sample chapter in InDesign that lead to other chapters, you could change all their target URLs in the Hyperlinks panel (all pointing to the same "this was a sample" page, for example) before you export to epub.

    Just an idea :D

  4. Hi Anne-Marie:
    Thanks, good ideas. I fuss with my files too much to go direct from ID to EPUB. It would mean making all those changes twice.

  5. This is a great post. Thanks, Liz. Just a quick question: Who adds the official looking link at the last page of the sample? Will Apple add that automatically to your sample or do you add it?


    1. Excellent question, I should have addressed that originally. Apple automatically adds the Buy button.

  6. I've been thinking on this, and the TOC and anchor-links part in the workflow seem a bit laborious. In the search for efficiency, I'm wondering, would the below work?

    Could we use GREP to make our "00xx" at the end of Apple's string match the playOrder="xx".

    This of course presupposes that Apple allows their com_apple_itunes_epub_end0000 string to start at, say 0007. Do they?

  7. I've made and submitted many books with previews before, but now iTunes Producer is starting to give me errors, claiming that I need to submit a preview with my read along book. It returns this error twice, sometimes up to 4 times:

    "Books with SMIL (read along) require a custom sample before they may be sold in the store." at Book (MZItmspBookPackage)

    I've purchased all of your books so far, and do my best to problem solve before I ask questions, but I can't seem to figure this one out. Are there new parameters/metadata that I need to set to distinguish my preview file? Or maybe these errors are just hinting that it won't validate because I missed something?

    Any help would be much appreciated. Thanks.

    1. If you are submitting a custom (valid) sample with a book and you get back the error that they are requiring a sample, I can't imagine what the problem would be. (My first thought is that maybe it's not valid, or maybe you haven't attached it? This is the sort of error I commit all the time.) If that's not it, I got an email not too long ago that offered support via the Book Forum, a Fax, the Contact Us module within iTunes Connect and last but not least by telephone: 1-877-206-2092. Perhaps give them a call?


More of my books