Skip to content
This repository has been archived by the owner on Mar 26, 2018. It is now read-only.

Tutorial for Newsstand with In App Purchase

Brian VanderZanden edited this page Nov 14, 2013 · 4 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 and you want to sell issues and provide auto-renewable subscriptions (note that non-renewing subscriptions are not supported).

If your app only provides free issues, see Tutorial for Newsstand with Free issues.


REQUIREMENTS

  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)

CREATE YOUR PUBLICATIONS

  1. Create your issues using the [HPub tutorial](How to package an HPub).
  2. Zip the publication and rename from zip to [Hpubs](hpub specification) (remember to select all the files and zip them, do not zip the folder)
  3. Upload the Hpubs to your web server. 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.

CREATE ISSUES ON ITUNES CONNECT

To sell an issue, you need to create a corresponding non-consumable product in 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 Non-Consumable.
  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.issues.january2013.

CREATE SUBSCRIPTIONS ON ITUNES CONNECT

To meet the App Store requirements for a Newsstand app, you must provide a subscription. You can create one on iTunes Connect, similarly to what you did for issues.

  1. From the iTunes Connect page for your application, select Manage In App Purchases.
  2. Click the Create New button.
  3. Select Auto-Renewable Subscriptions.
  4. Fill in all the required form fields. For each subscription you create, take a note of the Product ID (which will be similar to com.example.Baker.subscriptions.3months): you will need to add them all to the AUTO_RENEWABLE_SUBSCRIPTION_PRODUCT_IDS constant in Constants.h.

CREATE A SHELF.JSON FILE

  1. Create the shelf.json file following the instructions for Newsstand shelf JSON.
  2. Remember to add the correct product_id from iTunes Connect.
  3. Validate the shelf.json file with JSONLint to make sure it's correct.
  4. 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",
    "product_id": "com.example.Baker.issues.january2013"
  }
]

CONFIGURE YOUR SUBSCRIPTION MANAGEMENT SERVER

To use auto-renewable subscriptions, you need to implement a server following the Baker Server API. As described in the page, your server has to provide the endpoints for PURCHASE_CONFIRMATION_URL and PURCHASES_URL.

CONFIGURE BAKER WITH NEWSSTAND AND SUBSCRIPTIONS

  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). Bundle ID Configuration
  4. Replace the icon files (ios-icon-*.png, check the Apple Guidelines for reference).
  5. Within Xcode, open the Constants.h file inside the BakerShelf folder, and:
  6. Set NEWSSTAND_MANIFEST_URL to to the endpoint that returns the shelf JSON.
  7. Set PURCHASE_CONFIRMATION_URL to the endpoint that accepts a purchase confirmation.
  8. Set PURCHASES_URL to the endpoint that returns purchased issues and subscriptions.
  9. Set AUTO_RENEWABLE_SUBSCRIPTION_PRODUCT_IDS to the iTunes Connect Product IDs of your subscriptions (e.g. com.example.Baker.subscriptions.3months).
  10. (optional) Set POST_APNS_TOKEN_URL to the URL that will receive the APNS device token for the user (necessary for Push Notifications).
  11. Note that you don't need to set FREE_SUBSCRIPTION_PRODUCT_ID, as you don't need a free subscription when you have auto-renewable ones.

OPTIONAL CUSTOMIZATION

  1. Within Xcode, open file UIConstants.h inside the BakerShelf 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.

TEST AND PUBLISH

  1. Test your publication, subscriptions and downloads. To test purchases in the sandbox environment you will need to create an iTunes Connect test user. See the Apple documentation on Testing a Store. Remember that, before testing, you will need to sign out from your real Apple ID.
  2. If you have problems check the Problems and Debugging page or the In App Purchase FAQ.
  3. When you're ready, submit to the App Store.

This is the old repository of Baker Framework. It's not in use anymore. Please go to the active repository on BakerFramework.

Clone this wiki locally