WordPress Plugin: Decoupled (headless) support

Overview

Some sites use WordPress as an API and render the front-end separately using frameworks such as Next.js or Gatsby. On such a site, you are responsible for:

• Loading the tracking script on your front-end. Please refer to the Parse.ly documentation on how to add it.
• Rendering the metadata that will be crawled by Parse.ly.

The wp-parsely plugin can be used to provide the metadata and provides integrations with the REST API and WPGraphQL.

REST API

The plugin automatically adds a parsely field to REST API endpoints corresponding to the Tracked Post Types and Tracked Page Types selected in the plugin settings. By default, this would be the /wp-json/wp/v2/pages and /wp-json/wp/v2/posts endpoints along with the corresponding single resource endpoints. This choice of objects types can be further adjusted by using the wp_parsely_rest_object_types filter:

// Disable REST API output from pages, but enable for term archives.
add_filter(
	'wp_parsely_rest_object_types',
	function( $object_types ) {
		$object_types = array_diff( $object_types, array( 'page' ) );
		$object_types[] = 'term';
		return $object_types;
	}
);

The parsely field contains the following fields:

• version, which is a string identifying the version of the REST API output; this will be updated if changes are made to the output, so consuming applications can check against it.
• meta, which is an array of metadata for the specific post, page, or other custom post type.
• rendered, which is the rendered HTML of the metadata for the post, page, or other custom post type. This will be a JSON-LD <script> tag, or a set of <meta> tags, depending on the format selected in the plugin settings. The decoupled code can consume and use this directly, instead of building the values from the meta field values.

The rendered field is a convenience field containing the HTML-formatted metadata which can be printed to a decoupled page as is. This can be disabled by returning false from the wp_parsely_enable_rest_rendered_support filter.

// Disable rendered field output from the REST API output.
add_filter( 'wp_parsely_enable_rest_rendered_support', '__return_false' );

The REST API integration can be disabled by returning false from the wp_parsely_enable_rest_api_support filter.

// Disable all REST API output from the Parse.ly plugin.
add_filter( 'wp_parsely_enable_rest_api_support', '__return_false' );

GraphQL

If the WPGraphQL plugin is installed, the wp-parsely plugin will register a parsely field on the ContentNode interface, which makes it available on most post types by default.

Here is an example GraphQL query for a post. Documentation for each field is provided via the GraphQL schema.

query PostWithMetadata {
 post(
  id: 1
  idType: DATABASE_ID
 ) {
  id
  parsely {
   isTracked
   jsonLd
   rawJsonLd:jsonLd(removeWrappingTag: true)
   repeatedMetas
   scriptUrl
   version
  }
  title
 }
}

The GraphQL integration can be disabled by returning false from the wp_parsely_enable_graphql_support filter.

// Disable all GraphQL output from the Parse.ly plugin.
add_filter( 'wp_parsely_enable_graphql_support', '__return_false' );