Tutorial for Newsstand with Free issues

pieterclaerhout edited this page Nov 7, 2014 · 5 revisions

Using Baker is simple and even if there are some technicalities involved, it's doable with just basic technical knowledge.

This tutorial assumes that you choose the Newsstand publication support in Baker for free issues only. For paid issues, read here. If you're not sure, read here.


  1. A Mac with Xcode
  2. An Apple iOS Developer account (required to test Newsstand and publish to the store).
  3. A server (to store your issues)


  1. Create your issues using the HPub tutorial.
  2. Zip the publication and rename from zip to Hpub
    • remember to select all the files and zip them, do not zip the folder
    • the file extension must be filename.hpub, not filename.zip.hpub or filename.hpub.zip
  3. Upload each Hpub to your web server (just the Hpub). Test and make sure that you can download them from a browser. (e.g. http://example.com/publication/issue1.hpub).
  4. Prepare a cover thumbnail image in PNG format for each publication and upload them on the server as well.

Note that you won't have to put the hpub files in the books/ folder (or anywhere in your app really). They will have to go on an external server along with the covers and the shelf.json file.


  1. Create the shelf.json file following the instructions for Newsstand shelf JSON.
  2. Validate the shelf.json file with JSONLint to make sure it's correct.
  3. Upload the shelf.json file to your web server (e.g. to http://example.com/baker/shelf.json). Test that you can download it correctly.

Example shelf.json file with a single issue. Notice the path of the hpub and the cover files:

    "name": "a-study-in-scarlet",
    "title": "A Study in Scarlet",
    "info": "The original masterpiece by Sir A. Conan Doyle",
    "date": "1887-10-21 22:50:36",
    "cover": "http://example.com/a-study-in-scarlet/a-study-in-scarlet.png",
    "url": "http://example.com/a-study-in-scarlet/a-study-in-scarlet.hpub"


To meet the App Store requirements for a Newsstand app, you must provide a free subscription. You can create one on iTunes Connect. Follow Apple instructions to do that, we can't unfortunately provide support for the Apple side of things.

  1. You need to have your application already created in iTunes Connect (don't worry, it's not submitting anything yet).
  2. From the iTunes Connect page for your application, select Manage In App Purchases.
  3. Click the Create New button.
  4. Select Free Subscription.
  5. Fill in all the required form fields. Baker will need a reference to the Product ID, which will be something similar to com.example.Baker.subscriptions.free.


  1. Download and unzip the latest version from the website.
  2. Open Baker.xcodeproj in the latest version of Xcode.
  3. Change the Bundle ID in Baker to your own Bundle ID (which you can find on iTunes Connect).
  4. Replace the icon files (ios-icon-*.png, check the Apple Guidelines for reference).
  5. Within Xcode, open file settings.plist inside the Baker folder.
  6. Set newsstandManifestUrl to the full shelf.json URL (e.g. http://example.com/baker/shelf.json).
  7. Set freeSubscriptionProductId to the iTunes Connect Product ID of your free subscription (e.g. com.example.Baker.subscriptions.free).
  8. (optional) Set purchaseConfirmationUrl to the URL where you want to receive the ping when a user subscribes to your app (see Subscription-pingback).


  1. Within Xcode, open file settings.plist inside the Baker folder.
    There you can set many details about the shelf look and feel.
    Title color, info text color, button color, button text color, loading color and so on.
  2. Within Xcode, open file Baker/Supporting Files/en.lproj/Localizable.strings.
    There you can set the shelf title, button titles and messages related to downloading and archiving.


  1. Test your publication, subscriptions and downloads
  2. If you have problems check the Problems and Debugging page.
  3. When you're ready, submit to the App Store.