Usage

1. Publishing and managing articles from the Apple News list
2. Publishing from the post edit screen
3. Tips
4. Troubleshooting
5. Diagnosing Errors
6. Debugging API Requests
7. Getting Help

Publishing and managing articles from the Apple News list

Once the configuration steps are completed, you're ready to publish content to Apple News. If you've chosen to automatically publish your content to Apple News, all posts will automatically be pushed to your Apple News channel when published.

The Apple News menu in the dashboard takes you to a list of posts that are eligible for publishing to Apple News. Either click the top menu or the submenu labeled "Articles".

It includes all posts of the types you've selected in Post Type Options that are published.

The Apple News list gives you full control over all content in your Apple News channel. Let's look at all of the features available.

Columns

The columns of the table provide the following information about each post:

Title: The title of the post in WordPress.

Last updated at: The last time the post was updated in Apple News.

Apple News Status: This is the live status of the post in Apple News. It can be any of the following values:

• PROCESSING: The article has been published and is in processing.
• LIVE: The article has been published, has finished processing, and is visible in the News app.
• PROCESSING_UPDATE: A previous version of the article is visible in the News app, and an update is currently in processing.
• TAKEN_DOWN: The article was previously visible in the News app, but was taken down.
• FAILED_PROCESSING: The article failed during processing and is not visible in the News app.
• FAILED_PROCESSING_UPDATE: A previous version of the article is visible in the News app, but an update failed during processing.
• DUPLICATE: The article is a duplicate of another article and is not visible in the News app.

More about Article objects and status codes from the Apple News API Reference.

Sync Status: This indicates the status of the post as it is currently synced with Apple News. This can be any of the following values:

• Not published: Never sent to Apple News.
• Published: Live in Apple News.
• Pending: This status is used when the Asynchronously publish to Apple News setting is enabled and the WordPress cron job has not yet run and sent the article to Apple News. We recommend setting "Use Remote Images" to "yes" and setting "Asynchronously publish to Apple News" to "no" on the Settings screen for the best experience.
• Needs to be updated: Live in Apple News, but there are changes in WordPress that need to be sent to Apple News.
• Deleted: Previously published, but now removed from Apple News.

Search and filter posts

The fields at the top of the table can be used to filter posts by the following criteria:

Status: This is the current sync status of the post (see above).

Show Posts From and Show Posts To: Use a date picker to select posts that were published only within a certain date range.

Search: Use the box at the left to search posts by title, excerpt or content.

There are also standard pagination controls at the top and bottom to manually page through the posts.

Bulk publishing

Using the checkboxes at the left and the bulk actions menu at the top left, you can select multiple posts to publish.

1. Check off the posts you want to bulk publish or click the box at the very top to select all posts on that screen.
2. Select "Publish" from the bulk actions menu in the top left.
3. Click "Apply" next to the bulk publishing menu to start the process. You'll be taken to a screen where you can review the posts to be published.
4. If all looks OK, click the Publish All button to get started. Do not leave this screen until all posts are successfully published. When bulk publishing is complete, posts will be marked as status Success and the Publish All button text will change to Done.

Publishing Individual Posts

If you mouse over the row of any unpublished post in the table, you'll see an action for Publish. If you click the Publish link, it will immediately publish your article to Apple News.

If all goes well, you'll see the following success notice in the dashboard:

Please note that if you are using asynchronous publishing, you may not see the message immediately.

Downloading posts

You can download the Apple News format JSON file for any post, whether published or not, by clicking on the Download link pictured above. This will create a file with a name like article-1234.json where 1234 is the actual post ID.

If you're using these files with the News Preview tool:

1. Rename the file to article.json. The post ID is included by default in case you want to export multiple files so they won't overwrite each other, but News Preview requires all ANF files to be named exactly article.json
2. Save the file its own empty directory. News Preview will attempt to recursively register file observers and directory observers for every file and directory that is in the same directory as your article.json file. If you save your article.json to a well-populated directory like ~ or a directory with interesting permissions like /tmp, News Preview will fail to register all the observers, and then will refuse to load the article.

Unfortunately, if you're using bundled images, they don't export with the JSON file. This is in order to maintain compatibility with the widest range of web hosts since some won't allow us to dynamically produce a ZIP file containing all the post content. We recommend that you use Remote Images whenever possible, but it may be necessary to use bundled images when testing on a local webserver during the development process. To ensure that the article can open in the News Preview tool, simply put a copy of any referenced images in the same directory as the article.json file prior to opening it in News Preview.

Updating posts

Once a post is published to Apple News, the available row actions available change.

If you are not using automatic updates you can simply click Publish again to update the post. If the post needs updating, it will be noted as "Needs to be updated" in the Sync Status column. If the post does not need to be updated, nothing will happen when you click Publish.

Deleting posts

If you need to delete a published post from Apple News, simply click the Delete link next to that post and confirm that you want to delete it. Apple News will display a placeholder indicating that the post is no longer available.

Sharing posts

If you click the "Copy News URL" link, the plugin will display the direct link to the post in Apple News. If accessed from a device with the app installed, your post will open in Apple News. If clicked from a desktop or incompatible device, it will automatically redirect back to the URL for the post on your website, referred to as the "canonical URL".

Resetting a stuck post

Occasionally, an error might cause a post to get stuck in pending status. If you're certain this has happened and the post isn't ever going to publish, you can click the Reset link for the post and then try to publish it again.

Publishing from the post edit screen

Additional options for publishing articles are available on the post edit screen. If you are using the classic editor (not the new block editor, codenamed Gutenberg) please make sure you've enabled the Apple News meta box in your settings.

Here, you can enter post-specific information. Just as with any other plugin sidebar (Gutenberg) or metabox (classic editor), all of the information here saves when the post is saved, even if it's not yet published. This is especially useful if you're using automatic publishing. This allows you to preconfigure posts for Apple News before they go live.

Note: You must ensure that your post has been saved after making changes to these fields before publishing to Apple News, otherwise some information about your post may be missing when the plugin tries to push it to Apple's servers. The best workflow here is to ensure that you click the "Save Draft" link immediately before clicking the "Publish" button if automatic publishing is enabled, or clicking the "Update" button before clicking the "Publish" button in the Apple News sidebar.

All of the fields are organized into sections, and all of the sections are collapsed by default in order to not clutter the interface. Simply click on the desired section and the fields will be exposed, similar to the WordPress customizer.

If you're ready to publish the post to Apple News and it's already been published in WordPress, simply click the Publish to Apple News button at the bottom of the meta box. Please note that if you have automatic publishing enabled you will not see this button since the post will be automatically published to Apple News when it's published in WordPress.

Once the post is published, the button will be replaced with information about the post in Apple News:

Tips

In general, little effort should be required to prepare your content itself for publishing to Apple News once you've configured this plugin to your desired settings. Even so, these simple tips will help your content look its best:

Image Captions

The Publish to Apple News plugin relies on HTML5 markup for image captions in order to associate a caption with an image. If HTML5 support for image captions is not enabled in your theme, WordPress will print the caption as a plain paragraph, and there is no way for the plugin to distinguish the caption from any other paragraph text. The following code is required in your theme in order to use image captions with the plugin:

add_theme_support( 'html5', ['caption'] );

You can specify support for more HTML5 features beyond just captions, which is fine. However, support for captions, at a minimum, is required in order for the plugin to properly convert image captions.

You can read more about HTML5 support on the add_theme_support page on WordPress.org.

Controlling Image Placement

By default, images inserted in your content will be placed inline, and will follow WordPress placement rules. You may find your images will be presented better within Apple News if you take the time to set the appearance of each image. To do this, in the WordPress text editor, click on an image, which will display a contextual alignment menu. This will provide you with a series of simple granular controls, allowing you to determine more precisely where each image will be displayed when your post appears in Apple News.

Note that images smaller than the body width on a given device will always be aligned. If you want to display an image without alignment, make sure it's big enough to be full width.

Cover Images

The featured image on your post will be used as the default Apple News cover image. The image will displayed full width at the top of the selected post. If no featured image is found, the first available image in the post will be used as the cover and will be automatically removed from the body in order to avoid duplication.

You can also specify a specific cover image and caption on the post edit screen.

Video in Feed

Apple News also supports videos in the Apple News feed provided to readers in the app. If you have an HTML5 compatible MP4 <video> in your post, the first one that is detected will automatically be added to the Apple News meta data for use by Apple News. If your video includes a poster image, it will also automatically be provided to Apple News as the stillURL for that video.

More information on how videos are used in the Apple News feed

Image Galleries

You can add image galleries the same way you do in WordPress, by using the “Add Media” button in the WordPress editor. Once there, navigate to “Create Gallery” and choose any images you want. By default, galleries will be shown as a horizontal slide. If desired, you can change this to “Mosaic” style in the plugin settings. Captions in galleries are also automatically included in Apple News.

More about horizontal galleries in the Apple News Format Reference.

More about tiled mosaic galleries in the Apple News Format Reference.

Embeds

The following embeds in your WordPress content are supported by the plugin and automatically converted into Apple News components:

• HTML5 Audio
• HTML5 Video
• YouTube
• Vimeo
• Instagram
• Twitter
• Facebook

If you are using the Brightcove Video Connect plugin and you have contacted Apple to have them connect your Brightcove account to your Apple News channel, Brightcove videos embedded from either the Brightcove Gutenberg block or the Brightcove shortcode will be converted into embedded Brightcove videos. Note that Brightcove videos embedded in this way are not previewable using the News Preview tool and need to be published to your channel in order for video playback to work, since it needs to route through Apple's servers.

All other embeds are displayed as a box with a link back to the original article.

Advertisement

While this plugin is not responsible for managing advertising options for your Apple News channel, it does provide simple settings to help you prepare your content for this. Please see the Apple News Publisher and iAds documentation and terms on Apple's website for more information about advertising options on Apple News.

By default, your exported posts should be ready to include advertising content somewhere in the middle of your content. If you don't want your WordPress content to be prepared in this way, simply set the “Advertisement” option in the plugin settings to No.

Troubleshooting

Using the News Preview tool

Apple provides a handy tool called the News Preview tool to let you preview how posts will look in Apple News. You'll also need to install Xcode in order to use the Simulator for various iOS devices. Unfortunately there is currently no equivalent for non-macOS users.

To use the News Preview tool, open the tool and go to the News Preview menu and select Preferences.

Enter your channel ID which you can copy and paste from the Apple News API Settings.

You can then simply drag and drop any exported JSON file from the Apple News plugin. Please remember to rename the file to exactly article.json. If you are using bundled images, you must manually export those from WordPress (right clicking and saving to your desktop works fine) and place all of the images and the article.json file into a folder before dragging onto the News Preview tool.

If there are errors, the tool will let you know or simply display a check mark at the left if all is OK. You can then click on any of the available devices at the right to preview your content in that device. Note that if you make changes to the article.json file, the News Preview tool will automatically refresh the Simulator.

If you are on a Mac, we strongly suggest you try to resolve problems using the News Preview tool before reaching out for support.

Resolving Image Issues

We strongly recommend setting the "Use Remote Images" setting to "yes," as it allows Apple News to pull the images from your site via URL, rather than having to bundle your image files and send them along with your article. Please note that in order for this to work, your images must be publicly accessible, which is the case for most sites. However, if you're testing on a local development site, your images are likely not accessible and therefore you should set this to 'no'.

Checking for errors

If a post is stuck pending publishing to Apple News and no error notice was received in the WordPress dashboard, this likely means that a fatal error occurred during publishing. In order to find out what happened, please check your PHP error logs. This is important troubleshooting information to provide when asking for support. If you don't know where the error logs are located for your site, please ask your web host.

Post is stuck in pending

See resetting a stuck post.

Auto-Sync and WP-CLI/WordPress Cron

If you have the auto-sync options enabled (auto-publish when published in WordPress, auto-update when updated in WordPress, auto-delete when deleted in WordPress) note that the automatic synchronization will not work if the updates are made via WP-CLI or via a custom WordPress cron event. This is for two reasons: first, it is not only possible, but very easy, to update a significant number of posts at once using WP-CLI commands, which could result in a massive number of API requests being sent to Apple. Second, publishing to Apple News is restricted by user role, and commands run via WP-CLI or a custom cron event do not run in the context of a particular user, so this check cannot run. If you make changes via a WP-CLI command or custom cron task and want to send that data to Apple, you will need to manually publish or update those posts either via the post edit screen or via the bulk publishing interface on the Apple News post list.

Diagnosing Errors

If there is an error when publishing, the Apple News API will tell you the error message, and typically the location of the error in the article content. You can download the article content by going to Apple News > Articles in WordPress and clicking Download on the article that is having the issue. You will likely want to run the JSON for the article through a formatter (e.g., https://jsonformatter.org/) to make it easier to read. For example, if the API is telling you that the URL to your image is bad, and it gives a component path of components[0].components[1], you will need to look in the JSON under the components key, then the first item (arrays are zero-indexed, so 0 is the first item), then the components key within that item, and the second item in that array (index 1 is the second item). That will let you see exactly what part of the generated JSON Apple's API is having trouble with and should point you in the direction of what you need to fix or what might be being interpreted incorrectly by the plugin.

Debug API Requests

The API request can be output to the browser without sending it to Apple News to help debugging from the /wp-admin/admin.php?page=apple_news_index screen by pressing the "Debug" link. This will show the Article request object, and any Bundles, and Meta.

Getting Help

If the above fails and you need to ask the developers for help, there are some steps you can take to provide us with all of the information we will need in order to diagnose and reproduce your issue:

• Include any error text that comes back from the Apple News API on publish.
• Copy the contents of the post_content field for an article that is failing and put it in a Pastebin. Include the link to the Pastebin in your issue report. You can get the contents of post_content for the failing post from the WordPress database or from an export of articles.
• Export the JSON for the article that is failing from the main Apple News post list screen, paste the JSON into a Pastebin, and include the link to the Pastebin in your issue report.
• Enable debug mode in the Developer Tools section of the Settings screen and attach the error report via a Pastebin link.
• Include any PHP errors from your server that are related to Publish to Apple News in your issue report via a Pastebin link.