Apple News configuration

Before you start: the invitation, and three values from Apple

Apple News channels are invitation-only. Getting approved is the slowest part of the whole exercise, and this tool can't hurry it: it moves your posts from Ghost to a channel you already have. If you sign in at icloud.com and don't see News Publisher, your account hasn't been invited yet.

Once you're in, the tool needs three values from News Publisher: a channel ID, an API key ID and an API key secret. In News Publisher, open Settings, then Connect CMS, then the API Key section; Apple's own instructions walk through it. If the secret isn't shown, Replace API Key issues a new one, which breaks any other integration using the old key until you update it. Keep that tab open for the next step.

On the Ghost side, the site needs an Admin API key from a custom integration (Ghost → Settings → Integrations → Add custom integration), saved in Site settings on the dashboard. The tool uses it to register a webhook and to read each post.

The Install tab

1. Credentials. Paste the Channel ID, the API Key ID and the API Key Secret, and press Save changes. The secret is stored encrypted and never shown again; the field says "A secret is configured" once one is saved, and typing a new value replaces it.
2. Validate credentials. Makes a test call to Apple with the saved values, so a typo shows up here rather than on your first post.
3. Set up integration. Creates a post.published webhook on your Ghost site and fills the Design tab's accent colour and logo from your Ghost settings as defaults. It reports the webhook's status and target URL. If the automatic install fails, add the webhook yourself in Ghost (Settings → Integrations → your custom integration → Add webhook), with the event Post published, the target URL shown, and the secret from the reveal control below the button.

The webhook fires when a post is published. Editing a post after that doesn't send the edit to Apple News; use Resync on the Activity tab for that.

The Syndication tab

• Enable Apple News syndication. The master switch. Off, the webhook is ignored and nothing is sent.
• Which posts syndicate. All published posts; Only posts tagged with the opt-in tag (#apple-news unless you change it); or All posts except those tagged with the opt-out tag (#no-apple-news unless you change it). Both tags are internal, so readers never see them.
• Publish mode. Preview sends each article to your channel's review queue, visible only to its preview audience, so you can check how posts look before anyone else does; it's the recommended setting while you're getting started. Live publishes to the public immediately.
• Members-only content and Paid / tier content each get one of three treatments, so a free-signup post and a paid post can be handled differently:
  • Don't syndicate these posts.
  • Public preview only: the article stops at the post's preview line, and a post with no preview line isn't published at all. The article ends with the "Continue reading" text and a button linking back to the full story on your site; both are editable here, and default to "Read the full story on our website." and "Read the full story".
  • Full content: the whole post goes to Apple News, preview line ignored.

The Design tab

• Branding. Your publication logo and channel icon are channel-level settings in Apple News Publisher, not here; Apple stamps them on every article. What this tab has is the accent colour, used for buttons and links inside the article, and the logo URL shown in the "continue reading" footer of preview articles. Both are filled in from your Ghost site by Set up integration and can be changed.
• Fonts. Apple News renders a fixed set of system fonts, so the body and heading pickers list those. Code blocks always use Courier.
• Article header. Standard puts the feature image on top with the title and byline (By Author · Date) below it. Overlay puts the title and byline over the feature image on a dark scrim, falling back to Standard for a post with no feature image. Show the post excerpt as a subheading adds it under the title.
• Wider content on tablets. Fills more of the screen on iPad and desktop and slightly enlarges body text and headings. Phones are unchanged either way.

Extra content: three Ghost pages

Standing content that goes into every article comes from Ghost pages you write, chosen by page from a list; the setting keeps the page's slug, so renaming or deleting the page shows as "(missing: slug)" here until you pick another. Only the page's body is used, never its title or feature image, and a draft page works, so the content never has to appear on your website. Edits to the page in Ghost reach the next article you syndicate, or an existing one when you Resync it.

• Before the article. Appears under the headline and byline, above the first paragraph. A series note, for instance.
• After the article. Appears at the end of the story: a support pitch, a pointer to your newsletter. It's skipped on paywalled previews, which already end with the "continue reading" button.
• Instead of signup cards. Apple News can't collect email addresses, so Ghost signup cards are left out of articles. Pick a page to stand in for each one; a "subscribe on our site" pitch with a link button works well. Leave it at None and signup cards are simply dropped.

The Activity tab

Processing takes a minute or two after you publish, and then Apple may take several additional minutes to publish the article to your channel. Be patient: a post that hasn't shown up yet is usually still on its way. Once processed it appears in the Activity list. Each row shows the title, when it was sent, whether it's a Preview or Live, a link to edit the post in Ghost, and an open link to the article itself, which only works on an iPhone, iPad or Mac. You can use those links, or the channel link from News Publisher, before the channel is approved for the public; once a few articles look right, that's the moment to ask Apple to make the channel public, by whatever route came with your invitation.

Three actions per article:

• Make live promotes a preview article to the public.
• Resync rebuilds the article from the post as it is now in Ghost and the current Design settings. It's how an edited post, a changed font, or a new "before the article" page reaches an article that's already there.
• Delete removes the article from Apple News and from this list, so the post can be sent again later.

Publish a post manually pushes any published post to Apple News now, bypassing the tag filter; it's how you send the back catalogue, since publishing a post in Ghost is the only automatic trigger. A post that's already been synced is skipped, and so is one your Syndication settings rule out. The reasons it gives:

What travels, and what doesn't

Each Ghost card is rebuilt as a real Apple News component rather than a web page in a frame: paragraphs, headings, lists, images, galleries, callouts, headers, calls to action, quotes, asides, buttons, product cards, bookmarks, audio, video, selected embeds (test before use), dividers, code blocks and file cards. A toggle card arrives open and stays open, since Apple News has no toggling. Signup cards are replaced by the page you picked above, or dropped.

Two card types don't make the trip yet: HTML cards and Markdown cards, and with them any table they contain. Their content is left out of the Apple News version, so a post that depends on one is worth checking in preview before you make it live.

Using a leaky paywall?

If you're using a JavaScript-based solution like Outpost or PayGlue's "leaky" paywalls, which leave the post's access set to Public, be warned that Apple News will receive the full text of that content. Only Ghost's Public preview line, with a non-public access setting, protects content.

Contributor access

If you give a contributor an Apple News grant (Site settings → Users), use covers the Activity tab, including publishing a post manually, Resync, Make live and Delete; manage adds the Install, Syndication and Design tabs.