Guides and Sample Code

Developer

Apple News Format Reference

On This Page

Article Metadata

Apple News Format documents can contain various metadata that describe aspects of the article content and the JSON document.

Required Properties

None

Optional Properties

For best results, include as many of these properties as you can, even though they’re not required.

Property and type

Description

Version

authors

Array of Strings

The authors of this article, who may or may not be shown in the Byline component.

Note that this is not the same as the Author component that makes an author name part of the article.

This is the default value for the Accessory Text in the article tile in channel feeds and section feeds. It can be overridden for those feeds by accessoryText in the Create Article request.

1.0

campaignData

Object

A set of key-value pairs that can be leveraged to target your advertising campaigns to specific articles or groups of articles. See Targeting in the Advertising Guide for News Publishers for more information.

1.0

canonicalURL

String

The canonical URL of a web version of this article. If this Apple News Format document corresponds to a web version of this article, set this property to the URL of the web article. This property can be used to point to one version of the article as well as to redirect devices that do not support News content.

Including a canonical URL significantly improves the Twitter and Facebook posts about your articles when users share content on these services. Both services will use the canonical URL to extract image and text metadata.

If canonicalURL is omitted, devices that do not support News will not be able to display the article.

1.0

coverArt

Array of Cover Art

An array containing image URLs for cover art used in the Featured Stories section of the For You feed.

1.2

dateCreated

String

The UTC date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss±ZZ:ZZ) on which this article was created. This value may or may not be the same as datePublished.

1.0

dateModified

String

The UTC date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss±ZZ:ZZ) on which this article was last modified after it was published.

This date will be used instead of datePublished in the article tile if it is less than 48 hours later than datePublished; see About Article Tiles.

1.0

datePublished

String

The UTC date in ISO 8601 format (YYYY-MM-DDTHH:mm:ss±ZZ:ZZ) on which this article was first published. This date is used in the feed. Include this date when posting older content to make sure the articles don't appear at the top of your feed.

1.0

excerpt

String

This is usually the first bit of article content, but it can be an article summary. Although this property is optional, it’s best to define it in all of your Apple News Format documents.

Note that you should not use HTML tags or Markdown syntax for this property.

This text can appear in the article tile in feeds. It can also appear when an article is shared.

1.0

generatorIdentifier

String

A unique identifier for the generator used to create or provide this JSON document.

1.0

generatorName

String

The name of the generator or system that was used to create the JSON document.

1.0

generatorVersion

String

The version "number," as a string, of the generator used to create the JSON document.

1.0

keywords

Array of Strings

Keywords that describe this article. You can define up to 50 keywords.

1.0

thumbnailURL

String

The URL of an image that can represent this article in a News feed view (channel, topic, or For You). For best results, provide a high-resolution image. The image will automatically be scaled down to the correct size.

  • Supported image types: JPEG (.jpeg or .jpg), GIF, PNG

  • Minimum size: 300 px wide x 300 px high

  • Aspect ratio (width ÷ height): Must be between 0.5 and 3.0.

  • To improve the loading time of the article, use the same thumbnail images in the News feed that you use in the article. If you use the same images in both places and the image appears on the first screen of the article, the image moves with an animated effect from the feed to the article.

1.0

transparentToolbar

Boolean

A Boolean value that indicates whether this article should be shown with a transparent top toolbar that is overlaid on the the top portion of the article.

If you set this property to true, make sure to leave some room between the top of the article and the first readable component, and make sure the top portion of the article is predominantly dark or predominantly light.

Default value: false

1.0

videoURL

String

Defines the URL for the video that represents this article. A glyph will appear on the thumbnail of the article tile, allowing the video to be playable from For You, Topic, and Channel feeds.

The videoURL should be the same as the URL for one of the Video components in the article. For the best results or continuous playback for an opened article with a videoURL, make sure that the thumbnailURL property in metadata uses the same image file as the video component's stillURL.

Video URL must begin with http:// or https:// (preferred). The video must be in one of the supported HTTP Live Streaming (HLS) formats. Streaming using the M3U playlist format is highly recommended.

For more information on HLS, refer to the iOS developer documentation on HTTP Live Streaming, especially the following sections of the HTTP Live Streaming Overview:

1.1

Document Metadata Example

  1. {
  2. "datePublished": "2017-09-09T14:45:45+00:00",
  3. "dateCreated": "2017-09-08T12:41:00+00:00",
  4. "dateModified": "2017-09-10T12:41:00+00:00",
  5. "authors": [
  6. "Anne Johnson"
  7. ],
  8. "campaignData”: {"sport”:["football"], "event":["Superbowl"], "author":["John Appleseed"]}
  9. "generatorName": "Generator",
  10. "generatorVersion": "1.0",
  11. "thumbnailURL": "bundle://header.png",
  12. "canonicalURL": "https://example.com/articles/2015/original-article.html"
  13. }