Jetpack Hooks: Control Jetpack CDN

Note: We wrote this article with advanced users in mind; you’ll need some coding knowledge to accomplish these tasks. As always, enable Jetpack Backup so you can easily revert your site in case of a mistake. Hooks are a way for one piece of code to interact with or modify another piece of code. They make up the foundation for how Jetpack interacts with WordPress Core.

If you have questions about how to use these yourself, ask the Jetpack community in the forums. If you’d like to hire help, reach out to a service like Codeable. 

Site admins use Jetpack’s Site Accelerator — a lightning-fast, turnkey CDN for unlimited files — to speed up their websites while lowering bandwidth consumption.

No two sites are alike, so there may be times in which it makes sense to disable certain aspects of the CDN or change how it processes images. Today we’ll explore how to use hooks to modify the functionality of Site Accelerator and customize it for the specific needs of your site.

Before using hooks:

• It’s important to prefix your functions to avoid conflicts with themes or plugins. Here, we use the prefix jetpackblog_.
• There’s no need to edit theme files directly — use a functionality plugin to add code snippets safely.

CDNs cache images, which can cause problems while you’re testing or experimenting with design changes. You can prevent Jetpack from processing any images while making edits with the following snippet:

add_filter( 'jetpack_photon_development_mode', '__return_true' );

How to disable Site Accelerator

When you pair the powerful jetpack_photo_skip_image hook with some of the WordPress conditional functions, you get very granular control over when and where to serve images from the CDN. 

You may wish to disable the CDN if you use the same file name to represent images that periodically change — for example, a header image that alternates weekly, but whose filename is always headerimage1.jpg. Site Accelerator doesn’t clear its cache; instead, it caches images forever. To change an image, it must have a new file name, so the usual cache-clearing techniques won’t work.

Disabling the image CDN on pages

How to disable Jetpack CDN on specific pages:

To disable the CDN on specific pages, use the following conditional logic, alongside the jetpack_photo_skip_image hook.

function jetpackblog_101() {
  if ( is_page( 101 ) ) {
    add_filter( 'jetpack_photon_skip_image', '__return_true' );
  }
}
 
add_action( 'wp', 'jetpackblog_101' );

Or, the is_page() function can also be passed a slug.

function jetpackblog_home() {
  if ( is_page( 'home' ) ) {
    add_filter( 'jetpack_photon_skip_image', '__return_true');
  }
}
 
add_action( 'wp', 'jetpackblog_home' );

Disabling the image CDN on posts

The is_single() function is very similar to the is_page() function and works for any post type, except attachments and pages.

How to disable Jetpack CDN on specific posts

This is very similar to the page example above, but applies for single posts.

function jetpackblog_302() {
  if ( is_single( 302 ) ) {
    add_filter( 'jetpack_photon_skip_image', '__return_true' );
  }
}
 
add_action( 'wp', 'jetpackblog_302' );

Control caching based on image URL 

The jetpack_photon_skip_image filter is not the only way to control which images the CDN caches. By default, Jetpack caches both on-site and off-site images, so if you hotlink an image from an external site, you’ll also add it to the CDN cache. 

How to force Jetpack CDN to cache images on your own server

If you serve a dynamic image from an external site (e.g. the image changes periodically but the URL stays the same), the CDN cache will not update. In this situation, you may want to only cache internal images.

function jetpackblog_external( $skip, $image_url, $args, $scheme ) {
// Get your site URL, without the protocol
	$site_url = preg_replace( '~^(?:f|ht)tps?://~i', '', get_site_url() );

	/**
	 * If the image URL is from your site,
	 * return default value (false, unless another function overwrites).
	 * Otherwise, do not use the CDN
	 */
	if ( strpos( $image_url, $site_url ) ) {
		return $skip;
	} else {
		return true;
	}
}
add_filter( 'jetpack_photon_skip_for_url', 'jetpackblog_external', 9, 4 );

How to change the way Jetpack CDN processes images

By default, Jetpack automatically compresses images uploaded to the CDN. But some sites — say, a photography blog — may want to display images at the original quality, regardless of file size. This is where the jetpack_photon_pre_args filter comes in.

function sa_custom_params( $args ) {
	$args['quality'] = 100;

	return $args;
}
add_filter( 'jetpack_photon_pre_args', 'sa_custom_params' );

In the above example, the quality parameter is set to 100, which means images will be uploaded at full quality. If you want to make even more customizations, there are a variety of supported query arguments to fine-tune how Jetpack processes your images. 

Some brands may want to apply the same filters and setting to all images for consistency. Let’s take a look at one example, where the image quality is set to 100, a sepia filter is applied, and the metadata is stripped. 

function sa_custom_paramsfilter( $args ) {
	$args['quality'] = 100;
	$args['filter']  = 'sepia';
	$args['strip']   = 'all';

	return $args;
}
add_filter( 'jetpack_photon_pre_args', 'sa_custom_paramsfilter' );

Customize Jetpack’s Site Accelerator with hooks 

Jetpack’s Site Accelerator can improve the performance of your site. But sometimes, you need to customize its functionality to fit your specific situation. With a little bit of knowledge, you can create custom rules to optimize the way you use the CDN. Learn more about using conditional tags on your WordPress site or browse other hooks for CDN.