How to use Apple News module

Apple News module provides an easy way to get your Drupal site's content into Apple News.

The Apple News module contains the following submodules:

  • Apple News Example - A fully functional example to use as a base for your own module with a fully styled node export.
  • Apple News Extra - Additional preconfigured destinations including Instagram, Twitter and embedded video and other components.

Before You Start

Before you start you must have a working Drupal 7 site, permissions to administer modules and add code, and that you meet the Minimum Requirements.

To install Drupal see these guides: Quick installation and Quick installation for developers.

Drush is not mandatory but will make for an easier, faster installation.

Minimum Requirements

These are the minimum requirements for the Apple News module.

  • PHP version 5.4 and above. Version 5.3 and below will cause a fatal error.
  • Drupal 7. The late version of Drupal 7 is recommended.
  • PHP compiled with cURL support. Check by going to /admin/reports/status/php on your Drupal site and looking for 'curl'. If not enabled, do a Google search for 'enable curl php [your server type]'.
  • (Optional) Drush 5.9 and above. If Drush is installed, follow the Drush-based Installation guide from README.md files. Otherwise, follow the Manual Installation guide

Become Apple News Publisher

To publish content from Drupal to News, a publisher must first sign up for News Publisher and obtain Apple News API credentials from Apple.

Install Drupal module

Download Apple News module and its dependencies:

The module also depends on two PHP libraries (to see required versions please enable Apple News module):

After you enable the Apple News module you will see a warning message about missing libraries. Please download required versions or try auto-install (experimental feature). If you used auto-install feature please try refresh the page after you press Download and Unzip button and clear Drupal cache.

Please install Views module if you would like to see Apple News published content and build your custom reports.

Apple News modules

For more options on how to install the module please see README.md file.

Configure Apple News module

Follow these configuration instructions to start publishing your content.

Initial Settings configuration

  1. Visit https://www.icloud.com/newspublisher/ to get your credentials and create a news channel that your Drupal site will use.

  2. In your Drupal site, navigate to the "Apple news credentials page" (admin/config/content/applenews/settings) and add your Apple News credentials. Apple News module settings

  3. In your Drupal site, navigate to the "Apple news channels page" (admin/config/content/applenews/settings/channels) and add a channel ID from your Apple account. Please add one ID at a time. The channels are validated by the Apple credentials that you added to your Drupal site. If valid, it will fetch the channel information and add them to your site's list of channels. Configure Channels

Export Configuration

An export is code that defines how to transform data in a Drupal site so it can be pushed to Apple News. The Apple News module defines a simple export, while the applenews_example module defines a more usable style.

To get started, we suggest enabling the applenews_example module and using that as a starting point.

  1. In your Drupal site, navigate to the "Apple news export manager page" (admin/config/content/applenews).
  2. Add new export.
    • Nodes - Configurable node export - you custom layout with three default components enabled.
    • Nodes - Example styled node exprot - This is example layout and contains some pre-styled components.
  3. The next step is to configure your export. Export content to Apple News
  4. On the Edit page, the minimum requirements to properly configure a channel to an Apple News channel are:
    1. Under "General Settings" set "Content types", select the content types that should be processed with this channel.
    2. Under "Components" in the "Add new component" field, select a component. Apple News components
    3. Under "Metadata" set "Default channels and sections", select the channel (Apple News Channel) that this export will be tied to. This export channel will get nodes, process them, and send them to the selected channel for display in the Apple News app. Apple News module metadata settings
    4. Click Save Changes.
    5. After saving, you will see "edit" and "delete" options to the right of the new components we just added. Click on "edit".
    6. Configure the component. Most components will require that you specify source fields and the component will use the data in those fields as content in the component.
    7. Click Save Changes.

Node Configuration

Once a content type is enabled in an export/channel, the option to add the individual post is in the node's add/edit page. If a content type is not added to any channel export, these options will not be available on the node add/edit page.

  1. To add a node to the channel sent to Apple, select "Publish to Apple" in the "Apple News" tab. If you want to temporarily stop publishing to Apple, or make revisions to the post before publishing or re-publishing to Apple, deselect this checkbox. It is the equivalent to the "Publish/Unpublish" feature with Drupal nodes.

  2. Select one or more channels from the available list.

  3. For each selected channel, select an available "section" that it belongs to. ("Sections" are created on apple.com, where you initially created the channel).

  4. Once a node is initially published to an Apple news channel, it will display a general information section showing post date, share URL, and the section and channel where it is published.

Publish individual content to Apple News

Preview a Post Before Publishing

If you want to preview a post before sending it to Apple, you will need to first download and install the Apple "News Preview" Application.

  1. After saving the node, return to the node's edit page
  2. Find the "Apple News" tab, and click the "Download" link under "Preview." This will download a folder containing the specially formatted file needed by the News Preview App.
  3. Drag the whole folder into the App icon to open, and it will display the page just as the Apple News App will be displaying it.

Preview content

Delete a post from publishing

If you want to delete a post from a channel, but not delete the post itself, There is a delete link in the "Apple News" tab.

Troubleshoot

If you are having trouble installing the module or its dependencies, review the common scenarios below.

  1. Problem: I'm getting the error message that includes:

    shell Fatal error: undefined '['

    Solution: This means that your version of PHP does not meet minimum standards. Version 5.3 and below are not able to process the bracketed php formatting of the AppleNewsAPI library. Updating your version of PHP to 5.4 and above will fix this.

  2. Problem: I'm getting the error message that includes:

    shell SSL certificate problem: unable to get local issuer certificate

    Solution: This is a mis-configuration in your server setup. Depending on what server OS you are using, the fix is different. Please see this StackOverflow post "curl: (60) SSL certificate : unable to get local issuer certificate" for more information on possible fixes specific for your system.

  3. Problem: I'm getting the error message:

    shell Please download PHP-Curl-Class (version 4.6.9) library to sites/all/libraries/php-curl-class

    Solution: This means that the library has not been downloaded, the wrong version is in place, or the folder for the library is labeled wrong. Double check that the library was downloaded into sites/all/libraries/php-curl-class/[files start here]. Check that the version is 4.6.9 by opening up the composer.json file and search for "version": "4.6.9". Lastly, if still not resolved, make sure the folder is named php-curl-class and NOT something like php-curl-class-master or php-curl-class-4.6.9.

  4. Problem: I'm getting the error message:

    shell Please download AppleNewsAPI (version 0.3.7) library to sites/all/libraries/AppleNewsAPI

    Solution: This means that the library has not been downloaded, the wrong version is in place, or the folder for the library is labeled wrong. Double check that the library was downloaded into sites/all/libraries/AppleNewsAPI/[files start here]. Check that the version is 0.3.7 by opening up the composer.json file and search for "version": "0.3.7". Lastly, if still not resolved, make sure the folder is named AppleNewsAPI and NOT something like AppleNewsAPI-master or AppleNewsAPI-0.3.7.

Please consult drupal.org for any issues outside of this scope.

Useful links