Newsstand Kit Framework Reference

You use the Newsstand Kit framework to develop the client side of a Newsstand application. Through the Newsstand, users can browse through newspapers and magazines that are optimized for viewing on mobile devices.

The Newsstand Kit framework has three classes:

  • NKLibrary—Represents the application’s library of newsstand issues.

  • NKIssue—Represents a publication’s issue in the library.

  • NKAssetDownload—Represents an asset that is downloaded (or that has downloaded) from the application’s server.

    An asset can be a component of the online issue such as an HTML or image file. It can also be a compressed archive (such as a ZIP file) that, once uncompressed, contains all the components of an issue in a ready-to-display form.

In addition, the framework adds a property (via a category) to the NSURLConnection class. This property associates a URL connection with a downloading (or downloaded) asset.

A newsstand content application is capable of running in the background to start downloads or process delegate events related to issue assets. To request this capability, specify newsstand-content as the string value of one of the array elements of the UIBackgroundModes property in the application’s Info.plist file. This property also enables applications to be launched in the background via push notifications.

The following steps describe the general workflow for getting newsstand content when push notifications trigger the download. If push notifications are not involved, skip the first step:

  1. The server side of the application sends a push notification to client applications when there is a new issue to download.

    If an application is not running in the foreground when the notification is delivered, it is activated in the background (or launched into the background, if necessary) to download issue assets. Otherwise, you handle the notification as you would any push notification. See Local and Push Notification Programming Guide for information on how to send and handle push notifications.

  2. The client application communicates with its server and gets URLs locating the issue assets to download. It might also need to obtain the name and date of the issue from the server. In this phase it might also validate that the user is eligible for a subscription or perform any other required authorization.

  3. The client gets the shared NKLibrary instance and sends a addIssueWithName:date: message to it, passing in the issue name and date. This step creates an NKIssue object representing the issue and adds it to the library.

  4. With each URL locating a downloadable asset on the application’s server, the client creates an NSURLRequest object.

  5. For each downloadable asset, it then sends a addAssetWithRequest: message to the NKIssue object, passing in the NSURLRequest object. This call returns a NKAssetDownload object.

  6. It then calls downloadWithDelegate: on the NKAssetDownload object, passing in a delegate object that adopts the NSURLConnectionDownloadDelegate protocol.

  7. The delegate monitors the downloading of the asset and updates a progress indicator. When downloading is finished, it processes the downloaded asset.

    Processing might involve uncompressing an archive or other actions before moving the asset to the assigned location of the issue in the application sandbox.

While assets are being downloaded, the application could be suspended or even terminated entirely if, for instance, there is insufficient memory or the user force-quits the application. The application (assuming it has the newsstand-content property) is later relaunched into the background to handle the completion of the download or any authentication challenges or errors related to it. The procedure in this case is the following:

  1. When the application is launched, it can use the UIApplicationLaunchOptionsNewsstandDownloadsKey key to access an array in the launchOptions dictionary passed into the application:didFinishLaunchingWithOptions:. If there is an array, it contains the identifiers that caused the launch; these could be identifiers for downloads that have finished downloading that or could not complete downloading.

  2. It iterates through the array of NKAssetDownload objects from the downloadingAssets property of the NKLibrary object and calls downloadWithDelegate: on each of them. If it wants, the application can use the asset identifiers obtained in the previous step to check which asset downloads caused the relaunch.

  3. The NSURLConnectionDownloadDelegate object handles the asset downloads as it does normally.

The Newsstand Kit framework expects all calls of its methods to be made on the main thread; the NSURLConnectionDelegate Protocol methods are also invoked on the main thread.


Framework
/System/Library/Frameworks/NewsstandKit.framework
Header file directories
NewsstandKit.h