Integrate WordPress

  • Updated

Connecting WordPress to the Optimizely Content Marketing Platform (CMP) lets you publish your content directly to your site, as well as generate article previews. When used in combination with the CMP analytics plug-in, the CMP can surface content-centric analytics for all the articles published from the CMP to your site. Once the site has been added, you can edit your SEO fields directly from the CMP — making it simple to choose a category or an author for each individual article. The Integration currently supports WordPress standard post types, categories and tags only.

Prerequisites

There are a number of prerequisites that need to be met in order to successfully connect to your WordPress account. If you're unable to confirm these, please speak to your WordPress administrator before attempting to connect.

Failure to make a connection with your WordPress site is generally because of one of the mentioned prerequisites below. If you are having issues making a connection and have discussed the above with your WordPress Administrator, please contact the support team or your CMP representative.

  • WordPress Plugin – Certain features of the WordPress integration require the CMP plugin to be installed. This will ensure that users will be able to preview pages prior to publishing to websites, allowing for a greater user experience. Install the WordPress Plugin here.
  • User Account – Although the integration will authenticate with any WordPress user account, we recommend that your WordPress administrator creates a dedicated account for the integration to run as. This user account will need Administrator permissions. Without the correct permission level, publishing and the integration is likely to fail.
  • XML-RPC – The integration requires WordPress XML-RPC to be accessible in order to authenticate. Please ensure this is accessible prior to connecting the integration and your WordPress administrator confirms its capability to be used. Your IT team may also need to place the CMP publishing IP address on the allow list and ensure it can be used through your network configuration, caching and so on. If this is the case please ask your CMP representative for the IP address to use. You may also use the CMP User Agent of Welcome NodeJS XML-RPC Client as an extra security measure.
  • WordPress Authentication URL – the URL of your website, the login page a user accesses to log in and the URL for an integration can be personalized within your own WordPress setup, meaning they are not always the same. Please confirm the URL to be used for the integration to authenticate with xml-rpc with your WordPress administrator.
  • htaccess credentials (optional) – if your public WordPress site is password protected via .htaccess you will need additional login credentials to be supplied to the integration. In most cases this level of protection is only for internal or in-testing sites but if in doubt you should speak to your WordPress administrator.
  • Post Types & Taxonomy – CMP is configured to communicate with WordPress standard post types and taxonomies only. If you are using custom post types or taxonomies you will need to configure WordPress to accept standard types and convert where necessary.

Connect WordPress to the CMP

  1. Go to your avatar > Integrations > Website, CMS & Feeds.
  2. Select Add > WordPress.

    Integrations-WordPress-1.png

  3. Fill out the form with the necessary information, including the title of your website and public URL.

    Integrations-WordPress-2.png

  4. Select the website type and add the credentials in the username and password section to complete the process. To minimize risk of unauthorized access, WordPress credentials are securely stored in the database in encrypted form and only the microservice that communicates with WordPress has access to the decryption key.
  5. You should enable the JavaScript Snippet option because it eradicates potential risks that impact the snippet; something that cannot be guaranteed if the JavaScript gets added manually through WordPress.

The website becomes available in a task > Publishing > Add Channel > website.

Integrations-WordPress-3.png

Install the CMP WordPress plug-In

Installing the CMP plug-in lets you display content analytics reporting. 

Installation is similar to any other WordPress plugin installation. You can upload the plugin to your plugin directory (generally wp-content/plugins) or install through WordPress’ built-in web based installer. The plugin does not have any visible interface like option panel or such. If you have issues installing or using the plugin, contact support@optimizely.com.

After you integrate the CMP with your WordPress site (under CMS Accounts), and you receive licensed content from CMP, update PHP files (which should be done by a web developer).

Field mappings (author and custom data)

By default, every article that the CMP posts to WordPress includes the following data in the Custom Fields section of the post entry. If the Custom Fields section does not show at the bottom of a post, you may need to enable them by gong to Screen Options in the top right-hand corner of the page, and clicking the checkbox labelled Custom Fields.

When visible, you will see a section similar to the setup depicted below:

Integrations-WordPress-4.png

  • nc-author – The author, sent from CMP. If you are publishing licensed content or have authors that do not exist in WordPress, edit your theme files to display the provided author instead of the default WordPress user.
  • nc-image-link – The link to the featured image of the article.
  • nc-link – The link to the article on the publisher's site, which serves as a canonical link for licensed content, and should be displayed when such content is in use.

    If the publisher does not provide this link, you see a GUID in this field. Escalate this to support immediately by submitting a ticket to support@optimizely.com.

  • nc-source – The name of the publication. Put this value in the byline next to the author attribution.

A properly set up theme will look like the following:

Integrations-WordPress-5.png

Additional custom fields

In addition to the default fields above, you can pass data to WordPress using Custom Fields or and Labels in the CMP. The use of these can include passing additional images or videos, or providing values for plugins that you are using. If you send labels to WordPress, these display with a prefix of label_{label name}.

Code Samples

The following code samples implement changes to your theme. Test all code in a staging environment prior to adding it to your site. You may need to adjust the code samples based on your theme.

Codes for surfacing author and publisher information

/*
Drop this into functions.php to generate an "author, source" string.
The function generate_license_info produces a formatted string with
author and source name for use in the theme file that display the post.
*/

function generate_license_info() {
$license = '';
$nc_author = get_post_meta(get_the_id(), 'nc-author', 1); // Pull in the author custom-field
$nc_source = get_post_meta(get_the_id(), 'nc-source', 1); // Pull in the source custom-field
``` // Check if both the nc-author & nc-source field aren't empty,
// then assign it to $license string

if ( $nc_author != '' )
$license = $nc_author;

if ( $nc_source != '' )
$license = $nc_source; // Join the author name & source name together,
// separated by a comma for a complete byline.

if ( $nc_author != '' && $nc_source != '' )
$license = $nc_author . ' | ' . $nc_source;

return $license;
}

Codes for displaying author and publisher information in theme

To show the correct author and publisher information, edit the specific theme file for single posts. You should create a WordPress user named CMPuser when connecting your site to the CMP initially. When publishing licensed content choose the CMPuser from the list of authors in the article task as depicted below.

/*
For use in theme file where post is displayed.
You should set up a WordPress user called 'CMPuser' when connecting to the CMP initially.
When publishing licensed content, choose the 'CMPuser' user
*/

if ('CMPuser' == get_the_author_meta('user_login'))
{
printf(generate_license_info());
}

else {
pre_existing_author_code();
}

/*
Replace the above line of code with the theme's default function
to display author information (usually 'the_author()' in standard WordPress setups)
*/

Adding a canonical link

To display canonical links correctly for licensed content, add the following code to your theme's header.php file. If you are using the Yoast SEO plugin, you should disable the canonical link on single post pages. You can do this by adding the second snippet of code to your functions.php file.

Canonical in header

$canonical_url = get_post_meta( $post->ID, 'nc-link', true);

if (is_single() && !empty($canonical_url)) {
<link rel="canonical" href="<?php echo $canonical_url ?>"/>
}

else {
<link rel="canonical" href="<?php the_permalink(); ?>"
}

Disabling Yoast SEO on post pages (only applies if Yoast is in use)

function wpseo_canonical_exclude($canonical) {
global $post;
if (is_single()) {
$canonical = false;
}

return $canonical;

FAQs

How to link a WordPress site with CMP by authenticating with credentials

CMP users can link their WordPress blogs by authenticating their site with their credentials from inside the CMP. You need to provide their username, password, and domain path where their WordPress xmlrpc.php file lives. If your blog uses HTTP basic auth via .htaccess or other methods, you can provide your HTTP auth information as well. All credentials are AES-256 encrypted.Integrations-WordPress-6.png

How does CMP authenticate with XMLRPC?

To authenticate an account, CMP makes XML-RPC calls following the WordPress API spec. To authenticate and retrieve blog information, CMP makes an initial request to get any blogs associated with the provided credentials and domain via wp.getUsersBlogs. After authenticating an account, you can optionally default posts from the CMP to a specific author or draft post type. Depending on how a self-host install is configured, making XML-RPC calls may require placing CMP IPs on the allow list. These IPs are provided upon request.

How tags and categories are set up inside CMP?

To let you set tags, categories, and authors from CMP, CMP make calls to retrieve this data using the API endpoints specified in the WordPress spec for retrieving taxonomies and authors.

How does draft post work?

When publishing in the CMP, you can synchronize posts by draft before publishing. This creates a post with a post ID which is updated on future post synchronizations and can be converted to a live post at publishing time.