Newsstand Atom Feed 1.2

Transcription

1

2 Contents Newsstand Atom Feed Overview 3 About This Release 3 Metadata Details 4 Character Encoding 4 Basic Newsstand Issue Metadata Example 4 Basic Newsstand Issue Metadata Annotation 6 2

3 Overview Newsstand is feature of ios 5 that allows your readers to access the latest issue of your newspaper or magazine. You host your content on your web server and provide the App Store with an Atom feed that provides updated metadata and cover art for each issue as it becomes available. The Newsstand Atom Feed XML (described in this document) is used to enable the App Store to display your app with the cover art and metadata that is relevant to the latest issue. This document specifies the Newsstand Atom Feed XML format for managing Newsstand issue metadata. Newsstand issue metadata is displayed on your Newsstand app s product page in the App Store. The metadata provided should accurately reflect the issues and content that are available within your app. Newsstand issue metadata can be managed via the Newsstand Atom Feed or directly in itunes Connect. The Newsstand Atom Feed allows you to create new issues and update existing issues. The Newsstand Atom Feed is processed daily. The Newsstand Atom Feed is based on the Atom 1.0 format. More information about the Atom 1.0 standard can be found at About This Release Date/Version July 25, Version 1.2 April 20, Version 1.1 Changes Made Changed size requirements for the cover art icon. This icon must be at least 1024px on the long side. Added cover art size requirements for the new ipad. 3

4 Metadata Details Metadata Details Character Encoding All metadata files must use UTF-8 Unicode character encoding. UTF-8 efficiently encodes non-roman characters and helps to ensure that metadata displayed in the store is the same as was intended by the repertoire owner. Your metadata file should not contain a byte-order mark (BOM) as it is not necessary for UTF-8 encoded data files nor is it supported by itunes at this time. Incorrectly encoded metadata files or files that include a BOM will cause delays or may prevent your content from importing. Note that simply including encoding="utf-8" in your XML declaration is not sufficient. The file itself must also be correctly encoded for accented characters and punctuation to appear correctly in the App Store. Basic Newsstand Issue Metadata Example The example below uses a fictional monthly magazine, App Store Weekly, to illustrate how to deliver metadata and cover art for an issue. <?xml version="1.0" encoding="utf-8"?> <feed xmlns=" xmlns:news=" <entry> <id>613</id> <published> t07:00:00z</published> <news:end_date> t07:00:00z</news:end_date> <summary>in the latest issue, we cover the new Apple Newsstand API.</summary> <news:cover_art_icons> <news:cover_art_icon size="source" src=" <news:cover_art_icon size="iphone_multitasking_1x" src=" <news:cover_art_icon size="ipad_multitasking_1x" src=" <news:cover_art_icon size="ipad_multitasking_2x" src=" 4

5 Basic Newsstand Issue Metadata Example <news:cover_art_icon size="iphone_shelf_1x" src=" <news:cover_art_icon size="iphone_multitasking_2x" src=" <news:cover_art_icon size="ipad_shelf_1x" src=" <news:cover_art_icon size="ipad_shelf_2x" src=" <news:cover_art_icon size="iphone_shelf_2x" src=" </news:cover_art_icons> </entry> <entry> <id>614</id> <updated> t07:00:00z</updated> <published> t07:00:00z</published> <news:end_date> t07:00:00z</news:end_date> <summary>in the latest issue, we cover the new Apple Newsstand Kit framework.</summary> <news:cover_art_icons> <news:cover_art_icon size="source" src=" <news:cover_art_icon size="iphone_multitasking_1x" src=" <news:cover_art_icon size="ipad_multitasking_1x" src=" <news:cover_art_icon size="ipad_multitasking_2x" src=" <news:cover_art_icon size="iphone_shelf_1x" src=" <news:cover_art_icon size="iphone_multitasking_2x" src=" <news:cover_art_icon size="ipad_shelf_1x" src=" <news:cover_art_icon size="ipad_shelf_2x" src=" <news:cover_art_icon size="iphone_shelf_2x" src=" </news:cover_art_icons> </entry> 5

6 Basic Newsstand Issue Metadata Annotation </feed> Basic Newsstand Issue Metadata Annotation <?xml version="1.0" encoding="utf-8"?> XML Declaration (required ) The character encoding of your document must be defined. itunes only accepts UTF-8 encoding as it efficiently encodes non-roman characters. Important: The Newsstand Atom Feed XML file must not contain a byte-order mark (BOM). /feed <feed xmlns=" xmlns:news=" Feed (required ) The xmlns (XML namespace) attribute is required and is used to declare the namespace to which the tags and attributes in the XML are expected to conform. The namespace refers to Atom. To use tags and attributes defined in the itunes Newsstand namespace, you must declare an additional namespace: The tags specific to the Newsstand namespace start with the prefix news:. Any element without a namespace prefix is considered to be in the Atom namespace. Only one <feed> element can be defined in the XML. /feed/updated Updated (required ) This updated date should be set to the date the information within the feed was most recently updated. The Newsstand Atom feed will be processed only if the updated date is later than the updated date of the previous feed that was processed. Date elements in the Newsstand Atom feed should be expressed in RFC 3339 format. An uppercase "T" character must be used to separate date and time, and an uppercase "Z" character must be present if expressing the time in GMT. Note that the time does not need to be expressed in GMT; the following two values represent the same date and time: <updated> t00:00:00-07:00</updated> 6

7 Basic Newsstand Issue Metadata Annotation /feed/entry <entry> Entry (required ) The <entry> element block contains the elements of an individual newsstand issue. The feed may contain multiple <entry> element blocks. If you deliver multiple <entry> elements with the same <id> value, they represent the same entry. The updated timestamps should be different. /feed/entry/id <id>613</id> ID (required ) The <id> element is used to identify the individual newsstand issue. This is an internal identifier that will not be displayed to customers. A new issue will be created if the ID is not found on an existing issue. If the ID matches an existing issue, the issue will be updated. The ID is case sensitive and must be unique (unless you are updating existing content). /feed/entry/updated Updated (required ) The updated date should be set to the date the metadata for this issue was most recently updated. Existing issues will be processed only if the updated date is later than the last modified date of the issue. /feed/entry/published <published> t07:00:00z</published> Published (required ) The published date is the earliest date your issue will appear on the App Store. The App Store will display the issue that has the closest published date prior to the current date, provided the issue has not ended. If multiple issues have the same published date, the most recently updated issue will be displayed. The <published> date should be the same as the <news:end_date> of the previous issue. This ensures that there will be no gaps where no issue is available. /feed/entry/news:end_date <news:end_date> t07:00:00z</news:end_date> News End Date (optional ) The <news:end_date> is optional. If provided, this is the latest date your issue will appear on the App Store. The <news:end_date> must be after the published date. 7

8 Basic Newsstand Issue Metadata Annotation /feed/entry/summary <summary>in the latest issue, we cover the new Apple Newsstand API.</summary> Summary (required ) The <summary> element should contain a description of the issue. This information will be displayed on the App Store when this issue is current. The summary must be between10 and 2000 bytes. /feed/entry/news:cover_art_icons <news:cover_art_icons> <news:cover_art_icon size="source" src=" News Cover Art Icons (required ) The <news:cover_art_icons> element should contain at least one cover art icon. Each <news:cover_art_icon> specifies a cover art image for your issue. All cover art images should be.png files and have an aspect ratio between 1:2 and 2:1. A cover art icon with size name "SOURCE" is required. This icon must be at least 1024px on the long side. Apple will automatically scale the 1024px source to fit each device so you do not need to provide multiple images. However, if you have designed cover art specifically for each device, you can provide additional sizes of your cover art icon with the following size names: IPHONE_MULTITASKING_1X - icon must be exactly 57px on the long side IPHONE_MULTITASKING_2X - icon must be exactly 114px on the long side IPAD_MULTITASKING_1X - icon must be exactly 72px on the long side IPAD_MULTITASKING_2X - icon must be exactly 144px on the long side IPHONE_SHELF_1X - icon must be exactly 90px on the long side IPHONE_SHELF_2X - icon must be exactly 180px on the long side IPAD_SHELF_1X - icon must be exactly 126px on the long side IPAD_SHELF_2X - icon must be exactly 252px on the long side The size names are case sensitive. You cannot provide a size name that is not listed above. If you provide multiple images, those images should look identical or with only minute variations among the different sizes. The src attribute is required and should be the absolute URL to your cover art icon. </news: cover_art_icons> </entry> </feed> 8

9 Apple Inc Apple Inc. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, electronic, photocopying, recording, or otherwise, without prior written permission of Apple Inc., with the following exceptions: Any person is hereby authorized to store documentation on a single computer for personal use only and to print copies of documentation for personal use provided that the documentation contains Apple s copyright notice. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to assist application developers to develop applications only for Apple-labeled computers. Apple Inc. 1 Infinite Loop Cupertino, CA Apple, the Apple logo, ipad, and itunes are trademarks of Apple Inc., registered in the U.S. and other countries. App Store is a service mark of Apple Inc. ios is a trademark or registered trademark of Cisco in the U.S. and other countries and is used under license. Even though Apple has reviewed this document, APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS DOCUMENT IS PROVIDED AS IS, AND YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY. IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if advised of the possibility of such damages. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any modification, extension, or addition to this warranty. Some states do not allow the exclusion or limitation of implied warranties or liability for incidental or consequential damages, so the above limitation or exclusion may not apply to you. This warranty gives you specific legal rights, and you may also have other rights which vary from state to state.