Customizing Publicize Sharing Behavior

Publicize makes it easy to automatically share posts on Facebook, Twitter, Tumblr, LinkedIn, and Yahoo! VIP clients can customize which shortlink Publicize uses, when Publicize shares to which accounts, and other behavior changes using standard filters.

Conditionally allow services or connections to be utilized

Publicize includes an extremely helpful wpas_submit_post? filter for determining whether a given post should be submitted to a given service or connection. It looks like this:

$submit_post = apply_filters( 'wpas_submit_post?', true, $post_id, $service_name, $connection_data ) )

$service_name will be a value like ‘twitter’ or ‘facebook’, and $connection_data will have metadata about the connection.

Here’s how you might reserve a “@vipwpnews” Twitter account exclusively for posts in the “WordPress” category:

add_filter( 'wpas_submit_post?', 'vipx_wpas_submit_post', 10, 4 );
function vipx_wpas_submit_post( $ret, $post_id, $name, $connection ) {

	$categories = get_the_terms( $post_id, 'category' );
	if ( 'twitter' == $name && '@vipwpnews' == $connection['meta']['display_name'] ) {

		if ( is_array( $categories ) )
			$categories = wp_list_pluck( $categories, 'slug' );

		if ( empty( $categories ) || ! in_array( 'wordpress', $categories ) )
			$ret = false;

	return $ret;

Note: This filter is applied both when the post is published and in the post metabox to determine which services should appear as available to the writer or editor. It will also let authors add their own services.

Add a checkbox to send new post updates to Publicize

When liveblogging or making frequent updates to a post, you may want to send multiple updates to Publicize.

Publicize’s default behavior is to only syndicated a post once. You can add a checkbox for writers or editors to publicize a post a second time using this code snippet:

add_action( 'publicize_form', 'vipx_filter_publicize_form' );
function vipx_filter_publicize_form( $form ) {
	global $post;

	// Only add the checkbox if the post was already published
	if ( 'publish' != $post->post_status )
		return $form;

	$checkbox = '<label for="vipx-republicize"><input type="checkbox" id="vipx-republicize" name="vipx-republicize" /> Re-Publicize Post?</label>';

	$form .= $checkbox;

	return $form;

add_action( 'save_post', 'vipx_action_save_post_republicize', 5 );
function vipx_action_save_post_republicize( $post_id ) {

	if ( isset( $_POST['vipx-republicize'] ) ) {
		update_post_meta( $post_id, '_publicize_pending', true );
		add_filter( 'wpas_force_publicize', '__return_true' );

The message shared to the service will be whatever is in the Publicize textarea.

Implement your own URL-shortening service

By default the Publicize feature uses as a URL-shortening service. You can also use any other URL-shortening service that can return a shortened URL.

The easiest way is to filter pre_get_shortlink or get_shortlink (called by wp_get_shortlink). For an example, check out the plugin.

The following filter is available to alter the URL sent in your update:

$url = apply_filters( 'wpas_post_url', wp_get_shortlink( $post->ID, true ), $post->ID, $this->slug );

Altering the default messages

It is also possible to change the default message that is created with the following filters:

apply_filters( 'wpas_default_message', $this->default_message, $this->slug )
apply_filters( 'wpas_default_prefix', $this->default_prefix, $this->slug )
apply_filters( 'wpas_default_suffix', $this->default_suffix, $this->slug )

These filters are used in the following context:

$title = sprintf( $this->default_prefix, $url ) . sprintf( $this->default_message, $post->post_title, $url ) . sprintf( $this->default_suffix, $url );

and allow the wildcards '%title%', %url% within the default_message/prefix/suffix variables.

You can also alter the message that is sent to Twitter / Facebook with a simple function attached to the following filter to Twitter:

$status_update = apply_filters( 'publicize_twitter_message', $message, $post, $url );

and to Facebook:

$status_update = apply_filters( 'publicize_facebook_message', $custom, $post, $url );

Infinite Scroll

Some of the standard themes on support infinite scroll, meaning additional posts are loaded and displayed as you approach the bottom of the page. Our metrics have shown that this increases reader retention. You can see it in action at or

If you would like to add this functionality to your theme, please visit the Jetpack support page on Infinite Scroll.

By default on, Infinite Scroll is only enable on the home page. You can use the infinite_scroll_archive_supported filter to enable it in additional contexts within the theme.

For example:

function mytheme_infinite_scroll_archive_supported() {
    return is_home() || is_archive();
add_filter( 'infinite_scroll_archive_supported', 'mytheme_infinite_scroll_archive_supported' );

Note: when you enable Infinite Scroll, the posts per page value is changed to seven. Every Ajax load puts seven more posts and counts as one pageview.

Using Data from Stats

We’ve created various helper functions that make it easy to work with Stats data. You can find these functions in the following helper file: vip-helper-stats-wpcom.php. This file is auto-loaded for you.

Note: Please use these functions with care as they can be fairly resource-intensive and can cause issues if abused under high traffic scenarios.

Getting Most Popular Posts

The following helper function returns popular posts for a specified number of days: wpcom_vip_top_posts_array. It returns data in the raw format returned by the Stats API. If you don’t care much about the actual view count, you can easily use the returned post_id to fetch the full post objects.

This function fetches the list of posts (and pages) that have had the most views recently, and doesn’t do any filtering of the resultant data.

If you want to exclude pages from the listing on your sites, or previously popular posts that you have now deleted, then you need to add code to your theme to filter these out from display.

Getting Other Data

Using the wpcom_vip_get_stats_array function, you can retrieve the following data:

  • views (daily views)
  • postviews (top posts)
  • referrers (top referrers)
  • searchterms (top referring search terms)
  • clicks (top outbound clicks)
  • authorviews (top authors)

Stats API Stats has a nice API to fetch all sorts of cool data too! For access to this data outside of your site/theme, please read our documentation here.

Gravatars and Blavatars


A Gravatar is a Globably Recognized Avatar (and Profile), a service by Automattic that allows any person to assign an image to an email address. makes extensive use of Gravatars whenever possible, and we recommend using them in your theme and assigning a Gravatar to every author.

For user profiles and Gravatar management instructions, please visit the Gravatar and Public Profile pages on the support site.

To learn how to implement Gravatars in your site theme, please visit Using Gravatars in the codex.

Tip: If you are not seeing avatars on your site, check to make sure Avatar Display is enabled in Settings -> Discussion.


Blavatars are site icons which are automatically used on as the site favicon, iPhone home screen icon, etc.
You can set your site Blavatar under My Sites (top left corner) > Settings -> General tab in the Calypso dashboard.

Note: If your theme already contains a reference to an icon in the header.php file, the blavatar will be ignored.

You can also use the blavatar directly in your theme, with the following functions:

blavatar_exists( $domain )
get_blavatar( $url, $size = '96')


if ( blavatar_exists( blavatar_current_domain() ) )
    echo get_blavatar( blavatar_current_domain(), 128);


If you are not using Gravatars and Blavatars and need to disable the loading of related Javascript and CSS resources, you can use wpcom_vip_disable_hovercards() in your theme.

In case the built-in site favicon functionality, Blavatar, does not suit your needs, it can be disabled by calling wpcom_vip_disable_blavatar_icons() function from theme’s functions.php file.

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.