Object

Metadata

Information about your article, including author name, creation date, publication date, keywords, and excerpt.

Properties

authors
[string]

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.

This is the default value for the Accessory Text in the article tile in channel feeds and section feeds. It can be overridden by accessoryText in the metadata of the Create an Article request. See Create Article Metadata Fields and Changing the Appearance of Your Article Tile in Feeds.

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.

canonicalURL
uri

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.

If canonicalURL is omitted, devices that do not support News cannot display the article.

dateCreated
date-time

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.

dateModified
date-time

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 is used instead of datePublished in the article tile if it is later than datePublished by less than 48 hours. dateModified does not affect the feed order. See Changing the Appearance of Your Article Tile in Feeds.

datePublished
date-time

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.

excerpt
string

Some text representing your article. Typically it matches the first portion of the article content. It can also be an article summary. Although this property is optional, it’s best to define it in all of your Apple News Format documents.

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

See Changing the Appearance of Your Article Tile in Feeds.

Do not use HTML tags or Markdown syntax for this property.

generatorIdentifier
string

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

generatorName
string

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

generatorVersion
string

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

keywords
[string]

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

An array of links to other articles in Apple News.

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 is automatically scaled down to the correct size.

Supported image types are JPEG (.jpeg or .jpg) GIF, or PNG. GIF images provided as thumbnailURL are converted to JPEG for use as an article thumbnail.

The minimum size of the image must be 300 px wide x 300 px high.

The aspect ratio (width ÷ height) must be between 0.5 and 3.0.

To improve the loading time of the article, use one of the images in the article as the thumbnail image. 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. See Preparing Image, Video, Audio, Music, and ARKit Assets

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.

videoURL
uri

The URL for the video that represents this article. A glyph appears 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 preferably https://. The video must be in one of the supported HTTP Live Streaming (HLS) formats. Streaming using the M3U playlist format is highly recommended. See Preparing Image, Video, Audio, Music, and ARKit Assets.

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:

Discussion

For best results, include as many properties as you can even though they are not required.

Example

{ "metadata": { "excerpt": "2018 Super Bowl", "thumbnailURL": "bundle://SuperBowl.jpg", "datePublished": "2018-09-09T14:45:45+00:00", "dateCreated": "2018-09-08T12:41:00+00:00", "dateModified": "2018-09-10T12:41:00+00:00", "authors": [ "Anne Johnson" ], "campaignData": { "sport": [ "football" ], "event": [ "Superbowl" ] }, "generatorName": "Generator", "generatorVersion": "1.0", "canonicalURL": "https://example.com/articles/2015/original-article.html", "links": [ { "URL": "https://apple.news/AT6kNQslCQy6EE4bF8hpOoQ", "relationship": "related" } ] }}

Topics

Object

object Metadata.campaignData

Custom key-value pairs for use in advertisement campaigns.

See Also

Article Metadata

object LinkedArticle

A relationship between your article and another Apple News article.