Configuration
Once the Publish to Apple News plugin has been installed and activated, the next step is configuration. To begin, choose Settings > Apple News 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.
To enable content from your WordPress blog 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 Channel Info > API Key.
Please note that once you obtain your secret, it cannot be obtained again unless you replace the API Key. Once you have these settings, copy them into the API Key, Secret, and Channel fields at the top of the Apple News settings page.
Once entered and if your channel has been approved, you can begin publishing WordPress posts to Apple News.
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: Set this to 'yes' to automatically publish every post to your Apple News channel when it's published in WordPress.
- Automatically update Apple News: Set this to 'yes' to automatically update every published post in Apple News when it's updated 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.
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.
The Publish to Apple News plugin creates a default layout for Apple News. However, many of the individual component settings can be highly customized so you can create your own unique design for your Apple News content. Starting with version 1.2.0, we've also introduced a live web preview that shows an approximation of what your content will look like in Apple News. If you're on macOS, you can also see a live preview of all fonts that you select.
- All sizes are in points. Please enter only the number. Note that Apple does automatically adjust some font sizes automatically for different device screen sizes and orientations and therefore font sizes may not always be exact. If you want to test settings, please download Xcode and the News Preview tool.
- Colors can be selected using the WordPress color picker or by entering the HTML color code in
#123456format. - Font dropdowns show a live preview of the font on macOS only.
Layout margin: The left and right margins for components that aren't full width, such as the cover.
Layout gutter: The spacing between columns of components.
Read more about layout options in the Apple News Format Reference.
The body corresponds to the main paragraphs of text in your content. Anything enclosed in a <p> tag gets converted to a body component. You can format the body with the following options:
Body font size
Body font color
Body font hyperlink color
Body background color
Body alignment: Can be left, right or center.
Read more about formatting the body in the Apple News Format Reference.
The first letter at the beginning of your post can be converted to a drop cap, which is a large letter that span multiple paragraphs. It's a nice visual touch for your readers, though not required. You can format the drop cap with the following options:
Drop cap font
Use initial drop cap: Turns the drop cap on and off.
Drop cap font color
Read more about formatting the drop cap in the Apple News Format Reference.
The byline displays the article's author and publish date.
Byline font Byline font size Byline font color Byline format: Two tokens can be present, #author# to denote the location of the author name and a PHP date format string also encapsulated by #. The default format is "by #author# | #M j, Y | g:i A#". Note that byline format updates only preview on save.
Read more about formatting the byline in the Apple News Format Reference.
Headings are used for <h1> through <h6> tags that are present in your content.
Header font
Header font color
Header 1 font size
Header 2 font size
Header 3 font size
Header 4 font size
Header 5 font size
Header 6 font size
Read more about formatting headings in the Apple News Format Reference.
###Pull quote
Pull quotes are a block of text that can appear in the middle of your article to highlight an important quote or concept. These can be added when you publish.
Pull quote font
Pull quote font size
Pull quote color
Pull quotes also have a top and bottom border to make them stand out from the content.
Pull quote border color
Pull quote border style: can be solid, dashed or dotted.
Pull quote border width
Pull quote transformation: this can automatically uppercase the pull quote content.
Read more about formatting pull quotes in the Apple News Format Reference.
###Gallery
Gallery type: Can either be a standard gallery, or mosaic.
Read more about formatting galleries in the Apple News Format Reference.
###Advertisement
Enable advertisements
Ad Frequency: A number between 1 and 10 defining the frequency for automatically inserting Banner Advertisement components into articles. For more information, see the Apple News Format Reference.
Ad Margin: The margin to use above and below inserted ads.
Read more about advertisements in the Apple News Format Reference.
Drag these to change the order of the cover (i.e. your featured image), title and byline at the top of the article. Note that if you don't set a featured image, Apple News will automatically promote the first image in your post content to this location.
Advanced settings allow for control over additional options for global formatting and debugging.
This allows you to edit the global line height of three major components, the body, the pull quote and all headings.
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 two different types of issues:
Component Alerts: 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 settings to be alerted or automatically halt publishing.
JSON Alerts: If the plugin detects something that appears to be invalid in the final JSON document before pushing your content to Apple News, such as an exposed unicode character, this setting can be used to get a warning or 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.
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.