Introduction to Newsstand

PDF for offline use
Sample Code:
Related SDKs:

Let us know how you feel about this

Translation Quality


0/250

Applications that present news and magazine content can be listed in the iOS 5 Newsstand rather than the regular App Store – making it easier for users to find this type of periodical content. Newsstand applications must implement a subscription payment option and provide regular issue downloads in order to be approved by Apple. This article introduces the main features of Newsstand Kit to help you start building a Newsstand-compliant application. It also briefly discusses the UIPageViewController, which is not directly related to Newsstand but might find its way into your app because it provides a simple way to build an iBooks-like page-turning UI.

Overview

iOS 5 includes a new icon on the Home screen: Newsstand. It looks similar to a folder showing miniature app icons, except that it has a wooden-bookshelf background. Applications that present magazine and newspaper content can be published in the Newsstand – they do not appear outside of the shelf like ‘normal’ applications. Users will discover and purchase Newsstand applications in a special section of the App Store.

Newsstand applications must have a subscription-based product offering to be accepted into the App Store. Apple has introduced ‘free’ subscriptions as part of Newsstand so that free content can be offered. In-app purchases of single issues can also be sold, as long as there is a subscription-based option available.

Requirements

Using Xamarin.iOS with iOS 5 requires XCode 4.2 and the iOS 5 SDK from Apple, with Xamarin Studio 2.8 and Xamarin Xamarin.iOS 5.0.

Newsstand Basics

The Newsstand framework in iOS 5 offers the following new features for your application:

Newsstand app – Applications are presented on the Newsstand rather than with other application icons on the home screen.

Changing the cover icon – As new issues of your content are published the application can change the icon that appears in the Newsstand to reflect the latest issue.

Background downloads – Using Apple Push Notifications Service (APNS) your server can notify the application when new content is available. The application can detect this via a special payload key and automatically download content in the background (over wi-fi only).

File management – Content is stored in the application’s Caches directory and managed by the operating system. Newsstand applications inform the operating system when each issue is read, so that the operating system can intelligently delete older/unused content when storage resources are low.

Atom feed to iTunes Connect – You can supply your issue data to iTunes Connect via an Atom feed rather than data entry. This ensures that the App Store can display the latest cover and issue information to new users.

Getting listed in Newsstand

Getting listed has been simplfied is no longer set manually in Xamarin.iOS. Now you can open Info.plist in the plist editor, and check Newsstand downloads under 'modes', as illustrated below:

The application will automatically be listed in the Newsstand app (and be evaluated against the Newsstand requirements when submitted to the App Store).

When a Newsstand application is uploaded to Apple there are additional features enabled in iTunes Connect to manage the application, including specifying the Atom feed URL to supply new issue information for display on the App Store.

Once an application has been submitted to the App Store as a Newsstand app, it will always appear in Newsstand and cannot be reverted to a regular application.

Managing Icons

Newsstand applications have two sets of icons: the primary icon that appears in Settings/Search and a Newsstand icon that appears on the shelf.

Primary Icon – The primary icon is a square image that is presented with rounded corners, similar to any other iOS application. This icon will appear in the Settings app (if you have any user settings) and in Search results.

Newsstand Icon – The Newsstand icon is intended to represent the cover of a newspaper or magazine and therefore has fewer shape restrictions. This icon should be updated by your code as new issues become available. You can affect the way it is displayed with the BindingType and BindingEdge keys.

The Info.plist for a Newsstand application with both icons will look something like this:

<key>CFBundleIcons</key>
<dict>
<key>CFBundlePrimaryIcon</key>
<dict>
<key>CFBundleIconFiles</key>
<array>
<string>Icon.png</string>
<string>Icon@2x.png</string>
</array>
</dict>
<key>UINewsstandIcon</key>
<dict>
<key>CFBundleIconFiles</key>
<array>
<string>Issue.png</string>
<string>Issue@2x.png</string>
</array>
<key>UINewsstandBindingType</key>
<string>UINewsstandBindingTypeNewspaper</string>
<key>UINewsstandBindingEdge</key>
<string>UINewsstandBindingEdgeBottom</string>
</dict>

You can also create the Info.plist entries using Xamarin Studio. This screenshot shows the Info.plist included in the sample code in Newsstand.zip:

You can access basic plist editor in Visual Studio under your project's Properties, in the iOS Application tab. Keep in mind that there is no advanced plist editor available for Visual Studio.

This screenshot also shows the UINewsstandApp key (3 rd row) and the UIBackgroundModes key (3 rd from bottom) that are required for Newsstand applications.

Newsstand Push Notifications

To receive Newsstand Push Notifications, your application must register for them (which in turn prompts the user for permission). Include this statement early in your application lifecycle:

UIApplication.SharedApplication.RegisterForRemoteNotificationTypes (UIRemoteNotificationTypes.NewsstandContentAvailability);

and add a new entry newsstand-content to the string array key UIBackgroundModes in your Info.plist

On your server, add this payload key to your APNS message to notify the Newsstand application that new content is available for download.

{'aps':{'content-available':1}}

Handling this type of notification would normally involve starting a background download of the new content. The ‘content-available’ key should not be combined with an APNS message that you intend the user to see – if this key is present in a message then any text included will not be shown to the user.

To prevent applications using too much bandwidth, Apple limits applications to sending one APNS ‘content available’ message per 24 hour period. If your server generates additional messages they will be ignored (not forwarded to the device).

Setting up Newsstand in iTunes Connect

As with any new app, you will need to create a new iOS App in the My Apps section of iTunes Connect.

On the Versions page of your Newsstand app scroll down the page, and set the Newsstand switch to on. Fill in the required information and save it.

At this point you can upload your app, provided you have configured your Info.plist correctly.

Adding, editing, and deleting an issue is also done via iTunes Connect, under the Newsstand tab. To add an issue you must include the following:

  • Published Date.
  • Optional End Date.
  • Issue ID.
  • Summary.
  • Issue Cover Art.

You can find more information on setting up Newsstand in iTunes connect in the App Store Publishing guide.

Managing NKLibrary and NKIssues

The NKLibrary and NKIssue classes are provided to help you manage content that the user will download (ie. a free or purchased issue). These classes are not necessarily designed for you to model your complete issue library on, nor to keep track of purchases or subscription information. Your application should manage the list of purchase-able products and subscriptions itself, as well as the App Store in-app purchasing of those products. Only after a product can be accessed by the user should you create an NKIssue and add it to the NKLibrary.

Coding for NewsstandKit

Always access the SharedLibrary reference to work with Newsstand:

var library = NKLibrary.SharedLibrary;

NKIssue objects only have a few properties:

Name – Unique issue title.

Date – Publication date of the issue.

Status – Status of the issue’s content (None, Downloading, Available).

ContentUrl – The location in the /Library/Caches/Newsstand/ folder where the files for this issue are stored. This is generated by Newsstand as a read-only property that tells you where the data for an issue should be stored.

 

This code in Newsstand\SampleCode.cs demonstrates checking for the existence of an issue in the library and adding it if required. Only two properties can be set: Name and Date.

if (library.GetIssue ("Las Vegas") == null)
    library.AddIssue("Las Vegas", publishDate);

Downloading in the Background

NewsstandKit provides a new download mechanism specifically to enable APNS-triggered background downloading and installation of content (which could occur overnight while the device is not in use). Only Newsstand applications can use this API.

Downloading Assets

This code from Newsstand/SampleCode.cs demonstrates adding an asset to an issue and triggering a download. The content being downloaded is the xamarin.com home page HTML which is saved to a file, however applications can download any file type they choose. Apple’s documentation encourages the use of one file (eg. ZIP format) in preference to many smaller files (although either approach is possible).

var issues = NKLibrary.SharedLibrary.Issues;
var issue = issues[1] ; // New York
NKAssetDownload asset = issue.AddAsset (
    new NSUrlRequest(new NSUrl("http://xamarin.com/")));
newsstandDelegate = new NewsstandUrlDelegate1("NewYorkContent", issue);
asset.DownloadWithDelegate (newsstandDelegate);

The sample implementation for the download delegate is in the Newsstand/NewsstandUrlDelegate.cs file. It contains a subclass of NSUrlConnectionDownloadDelegate that implements the three methods required:

FinishedDownloading – This method is called when the asset has been successfully downloaded. The application must move or copy this file and process it in the background using UIApplication.SharedApplication.BeginBackgroundTask.

WroteData – Called repeatedly as the download is occurring. This method can be used to display and update a progressbar in the UI.

ResumedDownloading – When a download is restarted after being paused, this method is called.

The delegate methods are not called on the main thread, so be implementations that communicate progress or interact with the UI must ensure they do so safely. If multiple downloads are triggered then they are queued and executed serially.

Updating the Icon

Whenever new content is downloaded you should update the Newsstand icon to reflect the latest issue. This value on the UIApplication.SharedApplication instance and can be set to any image that you have downloaded as part of the issue or that you retrieve from the internet.

UIImage newcover = new UIImage(coverFile);
UIApplication.SharedApplication.SetNewsstandIconImage (newcover);

Reading issues

Whenever the user starts reading a new issue the library should be updated. If the application has a badge set for the number of unread issues, this should also be updated.

NKLibrary.SharedLibrary.CurrentlyReadingIssue = issues[1];
UIApplication.SharedApplication.ApplicationIconBadgeNumber = 0;

The sample code does not actually implement an issue library, a reader or an App Store purchasing model. These features are beyond the scope of this example.

UIPageViewController

The new UIPageViewController complements Newsstand by making iBooks-like page turning very simple to implement. This screenshot shows how it looks.

To use the UIPageViewController, add an instance to a ViewController and implement the following delegates:

SetViewControllers – Configures the UIPageViewController by passing the initial page (or two) and setting the direction.

GetNextViewController – The method that returns the ViewController for the next page in sequence.

GetPreviousViewController – The method that returns the ViewController for the previous page in sequence.

DidFinishAnimating – An optional method that is called after each page turn interaction, even if the page isn’t actually turned (for example, the user pulled down the corner of the page but chose to stay on the current page).

The file BookViewController.cs in the PageView example shows how to implement them.

Summary

This article has covered:

Newsstand applications – The main features of NewsstandKit and how to implement them with Xamarin.iOS.

UIPageViewController – How to implement iBook-like page turn animations.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.