Apple News

The Apple News integration provides the ability for content published in Brightspot to be delivered to Apple News. The integration requires that the site have a qualified Apple News Channel.

Once the Apple News integration is configured, editors will be able to take a number of administrative actions seamlessly within Brightspot, then see those effects in Apple News.

To familiarize yourself with the terminology used throughout this section, see the table below.

Term	Description
Apple News Channel	Represents your publication on Apple News. An Apple News Channel can be organized into multiple Apple News Sections.
Apple News Section	Comprises an Apple News Channel. You can create multiple Apple News Sections, but one must serve as the default.
Apple News Article	The content that is associated to an Apple News Section and makes up the content of an Apple News Channel.

Enabling integration globally

Before you can deliver content published in Brightspot to Apple News, you must first enable the Apple News integration at the global level.

To enable the Apple News integration at the global level:

1. Click > Admin > Sites & Settings > Sites > Global.

2. From the Integrations tab, expand the Apple News cluster.

3. Toggle on Enabled to enable the Apple News integration.

   Note

   The Task Host field inherits the value set up in Global > Main > Default Taskhost field. A task host is the name of the host where distributions and channel refreshes run. If this field is blank, please contact Brightspot Support.

4. Click Save.

Creating Apple News Channels

By accessing Apple News Channels, you can create a new Apple News Channel or edit an existing one. You can also filter on channels that have either a failed or successful distribution job status. This filter can also be used when searching Apple News Sections and Apple News Articles.

To create a new Apple News channel:

1. Click > Admin > Sites & Settings.

2. In the Sites widget, select the site for which you want to configure this setting.

3. Under the Integrations tab, expand the Apple News cluster, and locate the Default Channel field.

4. Using the following tables as a reference, complete the fields as needed.

   Click the tab names to view the fields table for that tab.

Main

Field	Description
Channel Name	The name of the Apple News Channel.
Channel ID	The ID of the Apple News channel. An administrator can find this ID in the News Publisher Console in Apple iCloud.
Stylesheet	The stylesheet you want to use for all Apple News Articles published in this Apple News Channel.
Advertisement Auto-Placement	Defines the automatic placement of ads at the channel level.

API

Field	Description
API Key	The API key of the Apple News Channel. This can be obtained by generating CMS integration credentials in the Apple News Publisher console.
API Secret	The API secret of the Apple News Channel. This can be obtained by generating CMS integration credentials in the Apple News Publisher console.
Advanced
Connection Settings	The Connection Settings allow you to extend the API client timeout durations for large article payloads. Select one of the two choices: None—Does not modify any of the connection settings for the Apple News Channel. Set—Exposes the fields necessary to modify the connection settings.
Connection Timeout	Set the timeout (in seconds) before the connection attempt is aborted (defaults to 10s).
Read Timeout	Set the timeout (in seconds) before the read attempt is aborted (defaults to 10s).
Write Timeout	Set the timeout (in seconds) before the write attempt is aborted (defaults to 10s).
Follow SSL Redirects	Toggle on to automatically follow redirects for SSL connections. This setting defaults to on.
Follow Redirects	Toggle on to automatically follow redirects for non-SSL connections. This setting defaults to on.
Cache Settings	The Cache Settings allow you to modify the standard browser request/response caching for Apple News. Select one of the two choices: None—Does not modify any of the cache settings for the Apple News Channel. Set—Exposes the fields necessary to modify the cache settings.
Disable Caching	Toggle on to disable the Apple News caching for this site. This setting defaults to off (caching enabled).
Force Caching	Toggle on to force caching of the Apple News channel for this site. This setting defaults to off (force caching is disabled).
Maximum Cache Size	Set the maximum size of the Apple News cache in MB.
Cache Duration	Enter the amount of time (in seconds) the content is cached, before it should be refreshed.
Always Revalidate	Toggle on to always have the cache revalidated. This setting defaults to off (no revalidation).
Prevent Content Transformation	Toggle on to prevent the transformation of content. This setting defaults to off (content transformation enabled).
Do Not Refresh Cache	Toggle on to prevent contacting the server more than once. This setting defaults to off (allows the recontacting of the server).
Tolerated Duration After Expiration	Set how long (in seconds) after which the cache expires and content is refreshed. This is the max-stale value.
Required Duration After Expiration	Set how long (in seconds) before its expiration the cache should refresh content. This is the min-fresh value.

Refresh

Field	Description
Enabled	Toggle on to periodically poll Apple News upstream to get new Apple News Channel information, or to refresh the Apple News Sections defined in Apple News. This allows refresh operations to run on the set cron schedule.
Cron Expression	The cron-based schedule on which the task will run.
Task User	The generic Brightspot user who will be associated with Apple News refresh task events. If a generic user does not already exist, it should be created and added to this task.
Run Immediately	Toggle on to automatically run the task off schedule when the Apple News Channel is updated.

5. Click Save.

Note

After the channel is saved, the Apple News Channel Quota, Apple News Share URL, and Apple News Distributions appear. See more information below the tables.

Additional widgets

Once the Apple News Channel is saved and the first refresh occurs, the following widgets appear:

• Apple News Channel Quota—Displays details about your channel's remaining quota for sending create and update requests, queue size, and wait time.

  

• Apple News Share URL—After the Apple News Article is successfully sent, this widget provides easy access to the story on Apple News.

  

• Apple News Distributions—Shows all distributions for all jobs sent to the channel.

  

Associating Apple News Channels to sites

After enabling the integration at the global level, you must associate an Apple News Channel to a site.

To associate an Apple News Channel to a site:

1. Click > Admin > Sites & Settings.
2. In the Sites widget, select the site for which you want to enable this feature, or select Global to enable this feature for all sites.
3. From the Integrations tab, expand the Apple News cluster.
4. From the Enabled list, select Enabled.
5. Under Default Channel, select an existing Apple News Channel.
6. Click Save.

Viewing Apple News Sections

Apple News Sections are pulled in via the refresh task. Each section contains a read-only view of the metadata that comes from Apple News, along with widgets for the Share URL, and distributions for content associated to the section.

To view Apple News Sections:

1. Click > Admin > Apple New > Sections.
2. Click the section you want to view. You are brought to a read-only content page pertaining to the section you selected. For details on these fields, see Overriding Apple News Section values.
3. Click Save. You return to the Apple News Sections search panel.

Overriding Apple News Section values

Apple News Sections are pulled in via the refresh task. Each section contains a read-only view of the metadata that comes from Apple News, along with widgets for the Share URL, and distributions for content associated to the section. You can apply overrides on certain values once an Apple News Section is ingested into Brightspot.

To apply overrides on an Apple News Section:

1. Click > Admin > Apple New > Sections.
2. Select an Apple News Section that has been ingested into Brightspot.
3. Using the table below, apply overrides to the Apple News Section.
4. Click Save.

Overrides descriptions

Field	Description
Overrides Tab
Stylesheet	Select a stylesheet to override the stylesheet being used for the Apple News Channel in which this Apple News Section appears.
Advertisement Auto-Placement	Select an override from the list to override the automatic placement of ads for all Apple News Articles within this Apple News Section.

Mapping Apple News Sections

Mapping from your site's section to an Apple News Section can be done either directly in the section or on the Section Mapping page.

To map to an Apple News Section directly from a section in Brightspot:

1. Click > Admin > Apple New > Sections.
2. Click the section for which you want to create a mapping. A content edit page appears.
3. In the Apple News Section Mapping widget, click Create Mapping. A page appears.
4. In the Apple News Section field, click . A content picker appears. Then, search for an existing section or create a new one.
5. Click Create Mapping. The page updates to display the mapping.
6. Click Save.

To re-map an Apple News Section directly from a section in Brightspot:

1. Click > Admin > Apple New > Sections.
2. Click the section for which you want to create a new mapping. A page appears.
3. In the Apple News Section Mapping widget, click Re-Map Section. A page appears.
4. In the Apple News Section field, click . A content picker appears. Then, search for an existing section or create a new one.
5. Click Create Mapping. The widget updates to display the new mapping.
6. Click Save.

To map to an Apple News Section from the Apple News Section page:

1. Click > Admin > Apple New > Sections.
2. In the Create widget in the bottom-left corner, click New Apple News Section Mapping. A form appears.
3. In the Section field, click . A content picker appears. Then, search for an existing section, or create a new one.
4. In the Apple News Section field, click . A content picker appears. Then, search for an existing Apple News Section.
5. Click Save.

Publishing an article to Apple News

Editors can publish content to Apple News using a Quick Create widget that appears in the article content edit form. The available options in the Quick Create widget depend on an editor's role-level and user-level permissions.

To publish an article to Apple News:

1. In the header, click .

2. From the Create list, select Article. A content edit form appears.

3. Complete the article fields as necessary. See How to make an article.

4. When you are ready to publish to Apple News, from the Quick Create widget, click Apple News Article. The existing article is copied and converted into an Apple News article.

   Note

   The new Apple News Article will have an Apple News Section applied to it based on Section Mapping configurations. For more information, see Mapping Apple News Sections.

5. Make any changes to the Apple News Article fields as necessary.

6. Complete your site's workflow and publish the Apple News article. You return to the article content edit form.

Note

Once you return to the article content edit form, a link to the Apple News article appears at the top of the content edit page. Additionally, the Apple News Article option in the Quick Create widget becomes disabled. See the image below.

Additionally, upon refresh, the Apple News Article Actions widget will have new options available. See Post-publish Apple News Article actions for more information.

Viewing Apple News Article generator identifiers

You can easily view the generator identifier for your Apple News Articles before you publish them from the content-edit page.

To view an Apple News Article's generator identifier:

1. Open an Apple News Article.

2. In the Apple News Article Actions widget, click Generate Article Document.

   This opens a pop-up with the JSON code for this article.

3. Locate "generatorIdentifier" and view the value.

   

This should be the same value as set in the Generator Identifier field in the Apple News integration. See Modifying Apple News Article generator identifiers for more information on changing this value.

Modifying Apple News Article generator identifiers

You can add a generator identifier to articles published to Apple News that indicate the article was published in Brightspot or some other customer identifier you determine as necessary. By default this value is set to Brightspot.

To modify the generator identifier:

1. Click > Admin > Sites & Settings > Sites > Global.

2. Click Integrations and expand the Apple News cluster.

3. Enter the desired generator identifier in the Generator Identifier field.

   

4. Click Save.

See Viewing Apple News Article generator identifiers for more information on confirming the correct value is set.

Apple News Article widgets

Once you publish an Apple News Article, a few new widgets appear:

• Apple News Article Actions—Provides a list of actions pertaining to the Apple News Article, including read and update operations.
• Apple News Article Synchronizations—Displays whether the Apple News Article in Brightspot is in sync with Apple News.
• Apple News Distributions—Shows the status of jobs sent to Apple News.
• Apple News Share URL—Allows quick access to the Apple News Article in Apple News.

Actions

The Apple News Article Actions widget has a few operations, including:

• Generate Article Document—Provides whole, compiled document for use for News preview. This allows you to download JSON for the Apple News Article and includes JSON styles and a button you can use to download the JSON.

• Read from Apple News—Provides data that Apple News has received after the Apple News article is submitted.

• Update in Apple News—Manually pushes an update to Apple News. To do this, update the article in Brightspot and republish, then click Update in Apple News.

  tip

  If the original article is updated, you must navigate to the Apple News article that is receiving the update, re-publish it, and then click Update in Apple News.

• Delete from Apple News—Removes the article from Apple News.

Synchronizations

The Apple News Synchronizations widget displays whether the Apple News Article in Brightspot is in sync with the source on Apple News.

The widget can contain one of three statuses:

• In Sync—Marked by a green circle, the Apple News Article is in sync with Apple News.
• Out of Sync—Marked by a red circle, the Apple News Article is out of sync with Apple News. An update request should be made.
• Unknown—Marked by a blue circle, the sync status of the Apple News Article is unknown. Either the remote state of the Apple News Article was not tracked, or the Apple News Article was taken down. A create or update request should be made to mark the article as in sync.

Distributions

The Apple News Distributions widget shows the status of the jobs sent to Apple News.

Share URL

The Apple News Share URL widget provides a link on which you can click to view the article in Apple News.

Bulk actions

When working with Apple News Articles, you have several bulk actions available to you.

Each of these options is available from the on the Search panel, after you search for and select multiple Apple News Articles.

Click the name of each bulk process to learn more.

Create

As you work on Apple News Articles, you can publish them individually using the Quick Create widget as described in Publishing an article to Apple News. However, you also have the option to publish several articles at once using the Bulk Create In Apple News option.

To use the Bulk Create In Apple News feature:

1. Open the search panel and search for Apple News Articles.
2. Select the box next to each article you want to create in Apple News.
3. Click in the upper right corner of the search panel.
4. From the menu that expands, click Bulk Create In Apple News.
5. Review the chosen Apple News Articles, and click Confirm to proceed with the bulk creation.

This kicks off the bulk creation event and a message is displayed. The message has a link that allows you to view the status of this event and address any issues that may occur.

After clicking the link you are taken to the Apple News Article Bulk Actions Event: Create page. This page has three tabs, Main, Job Status, and Translations.

• The Main tab provides an overview of the job, such as when the job was initially queued, who queued it, and what the current status is for this job.
• The Job Status tab provides detailed information about the creation job. Here you can see which articles were successfully created, failed creation, or are still pending creation. You can also click the link to the individual Apple News Articles to view a status page for each article in this process.
• The Translations tab lists any translation events that may be associated with the Apple News Article creation.

Update

After you have created articles in Apple News, you have the ability to make bulk changes to those articles using the Bulk Update In Apple News feature. Updates are made to the actual Apple News Articles in Brightspot, and then pushed to Apple News in one batch.

To use the Bulk Update In Apple News feature:

1. Locate and perform the updates to the desired Apple News Articles.

2. Open the search panel and search for Apple News Articles.

3. Select the box next to each article you want updated in Apple News.

4. Click in the upper right corner of the search panel.

5. From the menu that expands, click Bulk Update In Apple News.

6. Review the chosen Apple News Articles, and click Confirm from the confirmation pop-up to proceed with the bulk updating of the selected articles.

   A message is displayed with a link to view the progress of the bulk update process.

   After clicking the link you are taken to the Apple News Article Bulk Actions Event: Update page. This page has three tabs, Main, Job Status, and Translations.

   • The Main tab provides an overview of the job, such as when the job was initially queued, who queued it, and what the current status is for this job.
   • The Job Status tab provides detailed information about the update job. Here you can see which articles were successfully updated, failed the update, or are still pending to update. You can also click the link to the individual Apple News Articles to view a status page for each article in this process.
   • The Translations tab lists any translation events that may be associated with the Apple News Article update process.

Delete

The Bulk Delete From Apple News feature gives you the ability to start a bulk process to delete a batch of Apple News Articles from Apple News all at once.

To use the Bulk Delete From Apple News feature:

1. Open the search panel and search for Apple News Articles.

2. Select the box next to each article you want deleted from Apple News.

3. Click in the upper right corner of the search panel.

4. From the menu that expands, click Bulk Delete From Apple News.

5. Review the chosen Apple News Articles, and click Confirm from the confirmation pop-up to proceed with the bulk deletion from Apple News of the selected articles.

   A message is displayed with a link to view the progress of the bulk delete process.

   After clicking the link you are taken to the Apple News Article Bulk Actions Event: Delete page. This page has three tabs, Main, Job Status, and Translations.

   • The Main tab provides an overview of the job, such as when the job was initially queued, who queued it, and what the current status is for this job.
   • The Job Status tab provides detailed information about the deletion job. Here you can see which articles were successfully deleted, failed to be deleted, or are still pending to delete. You can also click the link to the individual Apple News Articles to view a status page for each article in this process.
   • The Translations tab lists any translation events that may be associated with the Apple News Article deletion process.

Promoting articles within Apple News Sections

You can promote articles within an Apple News Section.

To promote articles within an Apple News Section:

1. Click > Admin > Apple New > Sections.

2. Select the Apple News Section in which you want to promote an article.

3. In the Promoted Articles widget on the right, click Changed Promoted Articles.

4. In the Section field, select the Apple News Section in which you want to promote an article.

5. In the Articles section, click to search for an existing article, or create a new one.

6. Click to add additional articles to be promoted in the current Apple News Section.

7. Click Submit.

   The article name will now appear in the Promoted Articles field for this Apple News Section.

Stylesheets

Importing stylesheets

You can import an existing article.json file into Brightspot to determine how your articles display in Apple News. For more information on Apple News and JSON files, see JSON Concepts and Article Structure.

To import an Apple News stylesheet:

1. Click > Admin > Apple New > Stylesheets.
2. In the right-hand corner of the screen, click > Import New Stylesheet.
3. In the Name field, give the stylesheet a name.
4. Under File, click Choose, then browse and select the article.json file from your local storage.
5. Click Import.

To make additional changes to the article.json file manually, see Configuring stylesheets.

Configuring stylesheets

Brightspot gives you the option to import an existing article.json file to configure how your articles display in Apple News; however, you may opt to make additional changes beyond what is stipulated in this article.json file, or you may not have a file like this in the first place. In these cases, you can configure Apple News stylesheets manually in Brightspot. For more information on Apple News and JSON files, see JSON Concepts and Article Structure.

1. Click > Admin > Apple New > Stylesheets.

2. In the Create widget, click Create New Stylesheet. A content edit page appears.

3. In the Internal Name field, enter a name for the stylesheet. This name is used in certain widgets and in internal search.

4. In the Layout field, enter the following values, which Apple News applies to articles styled with this stylesheet:

   1. Columns—Number of columns.
   2. Width—Width of page.
   3. Gutter—Number of pixels making up the gutter.
   4. Margin—Number of pixels making up the margin on the page.

5. In the Layout Ordering field, determine the order of the fields that will render on the Apple News front end. For more information, see Planning the Layout for your Article.

6. In the Component Styles field, click to add components that are governed by the styles configured in the stylesheet. For more information, see Component styles.

   

7. Click Save.

Note

You may optionally click the Advanced tab at the top of the content edit page to do the following:

• Select a style for the description heading. This value defaults to H3.
• Set a transparent toolbar hat that is overlaid the top of the Apple News article.

Component styles

When you configure an Apple News stylesheet manually, you can define the layout and style for each article component.

To configure an Apple News stylesheet component style:

1. Click > Admin > Apple New > Stylesheets.
2. In the Create widget, click Create New Stylesheet. A content edit page appears.
3. Follow steps 3–5 in Configuring stylesheets.
4. In the Component Styles field, click to add components that are rendered by the stylesheet.
5. In the Component Type list, select the content type for which you want to define a component style.
6. In the Component Layout field, click and search for an existing component layout, or create a new one. This field defines properties for columns, width, gutter, and margin. For more information, see Apple News's Layout Properties.
7. In the Component Style field, click and search for an existing component style, or create a new one. This field defines style properties for components, including background color, border, and opacity. For more information, see Apple News's ComponentStyle Properties.
8. In the Component Text Style field, click and search for an existing component text style, or create a new one. This field defines the style for a text component, including font, spacing, and alignment. For more information, see Apple News's ComponentTextStyle Properties.
9. Click Save.

After-save

Events

You can use after-save events to automatically create, submit, or delete stories for Apple News.

To configure after-save events in Apple News:

1. Click > Admin > Sites & Settings.
2. Click , located to the left of , and type After Save Events.
3. Using the table below as a reference, enable the configurations as necessary.
4. Click Save.

Field	Description
Types	Select the content types for which you want to enable after-save events.
Auto Create New Apple News Article	Toggle on to automatically create a new Apple News Article for the article upon save, if one does not already exist.
Auto Submit To Apple News On Publish	Toggle on to automatically submit new versions of the article to Apple News upon publish. If not enabled, the editor must manually send any updated article to Apple News using the Create in Apple News option in the Apple News Article Actions widget. For details, see Apple News Article widgets.
Auto Delete From Apple News On Archive	Toggle on to automatically delete the article from Apple News when it is archived in Brightspot. If not enabled, the editor must manually delete the Apple News Article.

Rules

After enabling the Auto Create New Apple News Article after-save event (for details, see Events), you can configure additional rules to control which articles get sent to Apple News.

To configure after-save rules for Apple News:

1. Click > Admin > Sites & Settings.

2. Click , located to the left of , and type After Save Events.

3. Ensure Auto Create New Apple News Article is toggled on.

4. In the selection field, select Conditional.

5. Under Rule, select one of the following:

   • Any—Any of the criteria you designate must be met for this rule to be enforced.
   • All Match—All criteria you designate must be met for this rule to be enforced.
   • Source—The content must come from the source you designate for this rule to be enforced.
   • Section(s)—The content must belong to the sections you designate for this rule to be enforced. If selected, toggle on Include Secondary Sections to enable matching against all child sections (if any) of the section you select.

6. Click Save.

Viewing Apple News Distributions

All Apple News actions are visible on the Distributions page. Jobs can be filtered by whichever Apple News entities (like channels, sections, and articles) are relevant to the jobs.

To view an Apple News Distributions:

1. Click > Admin > Apple New > Distributions. . A Search Apple News Distribution Job search panel appears, listing all distributions from last activity date.
2. Using the available filters in the left panel, filter for distributions of relevance.
3. Click Save.