Configuration
Before you can use this plugin, you need to create an Apple News channel and complete an application for Apple to review. More information on this process is available from Apple at the following links:
Once you have started the application process with Apple, you will need to install and activate the Publish to Apple News plugin. To configure plugin settings, choose Apple News > Settings from the WordPress Admin panel.
This plugin is not responsible for setting up or managing your News Publisher channel with Apple, nor does using this plugin guarantee that Apple News will accept your content. Please see the Apple Developer and Apple News Publisher documentation and terms on Apple's website for complete information.
Once you've entered or updated settings, please remember to click the Save Changes button at the bottom of the screen.
To enable content from your WordPress site to be published to your Apple News channel, you must obtain and enter your Apple News API credentials from Apple. These can be found in your iCloud Publisher account under Settings > Connect CMS > Get an API Key.
Please note that once you obtain your secret, it cannot be obtained again unless you replace the API Key—so store it in a safe place, like a password manager. Once you have these settings, you can use them to create a .papi file and verify your connection to the Apple News API using the Apple News CLI tool.
Navigate to the Getting Ready to Publish and Manage Your Articles section of the Apple News API documentation and scroll to the section marked Get the Apple News API. Click on the link to download the Apple News API Client Utility and follow the instructions in the README to set up the CLI and create your .papi file. The .papi file's format is explained in the README, but here it is again for reference:
# Your Channel Name Here
endpoint: https://news-api.apple.com
channel_id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
key: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
secret: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Next, you need to verify your connection to the Apple News API using the CLI and the .papi file you just created. To do this, run the following command in a terminal:
papi-client channel getIf the Apple News API CLI was correctly installed, and your .papi file was created correctly, you will see a message like this:
===SUCCESS===
{
"data": {
"createdAt": "2016-01-01T00:00:00Z",
"modifiedAt": "2021-09-08T11:12:00Z",
"id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": "channel",
"shareUrl": "https://apple.news/xxxxxxxxxxxxxxxxxxxxxxx",
"links": {
"defaultSection": "https://news-api.apple.com/sections/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"self": "https://news-api.apple.com/channels/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"name": "Your Channel Name Here",
"website": "https://example.com"
}
}
If you do not get a success message, you will need to ensure that the Apple News API CLI is installed correctly and that your .papi file is configured properly. If you cannot connect via the Apple News API CLI, you cannot connect via the Publish to Apple News plugin, so it is important to get this step working before proceeding to configuring the plugin. If you have any difficulty with making a connection via the CLI, you will need to follow up with Apple support.
Once you have verified your connection, you can upload your .papi file to your WordPress site to grant the plugin access to publish, update, and delete articles on your channel. Navigate to Apple News > Settings and click Choose File next to Upload Channel Configuration File. Find and select your .papi file, which should be in your home directory. (On a Mac, you may need to press command + shift + period to view files that begin with a dot.) Select the file and click Save Changes.
Once configured, if your channel has been approved, you can begin publishing WordPress posts to Apple News.
If your channel is not yet approved, you can still configure the plugin, but you will need to push articles in preview mode. Apple will look at these sample articles when evaluating your channel for approval.
You will also notice a few more general settings underneath these fields. This determines how content will be published to your Apple News channel from WordPress.
- Automatically publish to Apple News when published in WordPress: Set this to 'yes' to automatically publish every post to your Apple News channel when it's published in WordPress.
- Automatically update in Apple News when updated in WordPress: Set this to 'yes' to automatically update every published post in Apple News when it's updated in WordPress.
- Automatically delete from Apple News when deleted in WordPress: Set this to 'yes' to automatically delete posts from Apple News when they're deleted in WordPress.
- Automatically delete from Apple News when unpublished in WordPress: Set this to 'yes' to automatically delete posts from Apple News when they're unpublished in WordPress.
- Automatically delete from Apple News when moved to the trash in WordPress: Set this to 'yes' to automatically delete posts from Apple News when they're moved to the trash in WordPress.
- Asynchronously publish to Apple News: Publish to Apple News using a single scheduled event rather than on publish. This is generally only necessary if you're forced to use bundled images and you're having issues with timeouts on publish. We generally recommend leaving this set to 'no' and using remote images.
This allows you to choose the post types that are eligible for publishing to Apple News. If you have multiple custom post types, you may not want them all to publish to Apple News and this gives you granular control.
If you are using the classic editor, you can also choose whether or not you want a meta box for handling per post settings and publishing to Apple News on the post edit screen. We recommending setting this to 'yes' as it's the most convenient way to handle publishing to Apple News right where you're already editing. If you are using the block editor, there is an Apple News plugin area in the top right that users can hide and show according to their own preferences.
Since version 1.2.2, formatting settings have been replaced by Themes.
Advanced settings allow for control over additional options for global formatting and debugging.
Alerts allow you to be notified of issues while publishing content. They can be set to one of three options:
none: Generates no alerts.
warn: Generate an alert when an issue is encountered.
fail: Generate an alert and halt publishing to Apple News when an issue is encountered.
Alerts can be enabled for components. These are generated when something is detected in your post content that cannot be published to Apple News, such as an unsupported HTML tag or embed. Although the plugin automatically removes these components, it may make your content look broken in Apple News. Therefore, you can use this setting to be alerted or automatically halt publishing.
As of version 1.2.0, all warnings provide direct links to the support forums for the plugin on WordPress.org and github so you can easily report issues.
Use Remote Images? This is where you can specify whether or not to use remote images. The Apple News API originally required all images to be bundled with the content in the API request. However, it can now download the images remotely after the API request is made, which is referred to as using remote images. This is much faster and virtually immune to timeouts when publishing. Therefore, it is strongly recommended you set this to 'yes'.
If your images are not publicly accessible, such as in a local development environment, you should set this to 'no' and use bundled images. To use remote images, the Apple News API must be able to access your images at a publicly available URL.
Use Full-Bleed Images? This setting overrides the normal display settings for images so that they span edge-to-edge without a gutter. This setting works best with landscape-oriented images.
Enable HTML Support? When this setting is enabled, body, heading, and quote fields will use Apple News HTML format instead of Markdown, which allows for certain inline formatting options to be applied, such as <code> and <pre> tags. This setting is on by default and is strongly recommended for all users.
To assist with troubleshooting, you can enable debugging. This will automatically send an email to the specified address every time a post is published with the full request and response from the Apple News API. When reporting an issue, this information can be invaluable for us to help you with troubleshooting.
If you are lucky enough to have test sites which are separate from your production site, you can prevent articles from your test site from publishing to Apple News by making use of the apple_news_skip_push filter. While the mechanism of determining if your site is the production site will vary on your particular installation, the basic structure will look something like this:
function my_site_skip_apple_news( $post_id ) {
return ! is_this_your_production_site();
}
add_filter( 'apple_news_skip_push', 'my_site_skip_apple_news', 10, 1 );
To change the behavior of a custom filter depending on whether Publish to Apple News is exporting an article or not, you can use the apple_news_is_exporting() function:
function my_site_content_filter( $content ) {
if ( function_exists( 'apple_news_is_exporting' ) && apple_news_is_exporting() ) {
return my_custom_apple_news_content_filter( $content );
}
return $content;
}
add_filter( 'the_content', 'my_site_content_filter', 10, 1 );