Skip to content

Tutorial for Newsstand with In App Purchase

pieterclaerhout edited this page Nov 7, 2014 · 6 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 and handle In App Purchase validation and tracking)

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. To learn more about the Baker Framework's Open Source server backend, you can read more information on the Baker Framework Baker Cloud Console (CE) website.

There are also other Third-Party Server options available. You can read more about those here.

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 settings.plist file inside the Baker folder, and:
  6. Set newsstandManifestUrl to to the endpoint that returns the shelf JSON.
  7. Set purchaseConfirmationUrl to the endpoint that accepts a purchase confirmation.
  8. Set purchasesUrl to the endpoint that returns purchased issues and subscriptions.
  9. Set autoRenewableSubscriptionProductIds to the iTunes Connect Product IDs of your subscriptions (e.g. com.example.Baker.subscriptions.3months).
  10. (optional) Set postApnsTokenUrl 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 freeSubscriptionProductId, as you don't need a free subscription when you have auto-renewable ones.

OPTIONAL CUSTOMIZATION

  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.

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.
Clone this wiki locally