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 themeta
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' );
Last updated: August 16, 2023