Integrate automatic updates to free or premium WordPress plugins and themes


Introduction

In this tutorial we'll show you how to integrate automatic updates with download key authorization to your free or premium WordPress plugins which are not hosted on the WordPress Plugins repository. Steps will be the same for WordPress themes too. We will assume that you've already configured your UpdaterCloud update server, created a new WordPress plugin release and that the update channel for your WordPress plugin is accessible. Alternatively, please check the Quickstart guide first.

Integrate the Update Checker

First thing you'll have to do is download the WP UpdaterCloud plugin and theme update checker. Unzip the files and place the wp-updatercloud directory in the root directory of your plugin (where the plugin main file is, or for themes, where the theme's functions.php file is located). Then edit your plugin main file (or function.php for themes) and add the following code.

{warning} Make sure to replace the {{SUBDOMAIN}} with your personal UpdaterCloud subdomain and the {{UPDATE_CHANNEL_ID}} with your UpdaterCloud update channel id.

/**
 * Integrate UpdaterCloud automatic updates.
 */
require_once plugin_dir_path(__FILE__) . 'wp-updatercloud/wp-updatercloud.php';

$updaterCloud = UpdaterCloud_v4_Factory::buildUpdateChecker(
    $url = 'https://@{{SUBDOMAIN}}.updatercloud.com/api/v1/update-channels/@{{UPDATE_CHANNEL_ID}}.json',
    $fullPath = __FILE__,
    $slug = 'wp-helloworld-plugin',
    $checkPeriod = 12,
    $optionName = '',
    $muPluginFile = '',
    $downloadKey = get_option('wp_helloworld_plugin_downloadkey'), // only needed for Premium plugins and themes
    $gatherAnalyticsData = true
);

Code breakdown

First we include the wp-updatercloud/wp-updatercloud.php file. Then create a new instance of the update checker, passing the following variables:

  • $url: This is your UpdaterCloud update channel url for this plugin. You may want to use different update channel urls for dev and stable releases and offer an option to your customers to select what channel to use for updates. All you need to do is save the user preference in an option (e.g. wp_helloworld_plugin_update_channel) and do something like the following to set the update channel url.
if (get_option('wp_helloworld_plugin_update_channel', 'stable') == 'dev') {
    $url = 'your update channel url which serves stable and dev releases';
} else {
    $url = 'your update channel url which serves only stable releases';
}

$updaterCloud = UpdaterCloud_v4_Factory::buildUpdateChecker(
    $url,
    ...
);
  • $fullPath: The full path to your plugin main file, or, in case of themes, the full path to your theme's functions.php.
  • $slug: Your plugin or theme slug.
  • $checkPeriod: How often should we check for updates.
  • $optionName: Where to store book-keeping info about update checks (transient name).
  • $muPluginFile: Full path to your MU plugin main file.
  • $downloadKey: Download key entered by the user in plugin settings and saved in this example in the wp_helloworld_plugin_downloadkey option.
  • $gatherAnalyticsData: UpdaterCloud can gather some analytics data about your customer websites (WP version, blog language, PHP version, installed plugin version, etc). In this example, we've just set this to true, but you should store the user preference in an option.

{warning} You must ask your customer for permission to gather and store analytics data from their website.

The download key field (premium plugins and themes only)

To identify the user requesting an update for their WordPress plugin or theme, we have to create a way for the user to enter his/hers download key, so it can be passed by the update checker to UpdaterCloud when requesting updates. This way, the UpdaterCloud update server can accept or reject the download by validating the provided download key (e.g. check if the download key is valid and allows access to the requested plugin or theme updates, etc). In this plugin example, we've stored the user provided download key in an option.

{info} For simplicity, in this plugin example we have't used download key validation or activation. To integrate download key validation or activation, please check the respective tutorials.

<?php

/**
 * Plugin settings menu.
 */
function wp_helloworld_plugin_settings_menu()
{
    add_options_page('Hello World Plugin', 'Hello World Plugin', 'read', 'wp-helloworld-plugin', 'wp_helloworld_plugin_settings');
}
add_action('admin_menu', 'wp_helloworld_plugin_settings_menu');

/**
 * Plugin settings.
 */
function wp_helloworld_plugin_settings()
{
    $saved = false;

    if (isset($_POST['save']) && check_admin_referer('wp_helloworld_plugin_settings', 'wp_helloworld_plugin_settings_nonce')) {
        $downloadKey = isset($_POST['wp_helloworld_plugin_downloadkey'])
            ? sanitize_text_field(wp_unslash(wp_strip_all_tags($_POST['wp_helloworld_plugin_downloadkey'])))
            : '';

        // Here you can validate or activate the provided download key, before saving it to database.
        // Please see the download key validation and/or activation tutorials.

        // Once done validating/activating the download key, update the option
        update_option('wp_helloworld_plugin_downloadkey', $downloadKey);

        $saved = true;
    }

    $downloadKey = get_option('wp_helloworld_plugin_downloadkey', ''); ?>

    <div class="wrap">
        <h1><?php echo __('Hello World Plugin', 'wp-helloworld-plugin'); ?></h1>
        <?php if ($saved) : ?>
            <div id="message" class="updated fade">
                <p><strong><?php echo __('Settings saved.', 'wp-helloworld-plugin'); ?></strong></p>
            </div>
        <?php endif ?>
        <h2>
            <?php echo __('Please enter your download key.', 'wp-helloworld-plugin'); ?>
        </h2>
        <form method="post" action="">
            <div>
                <?php wp_nonce_field('wp_helloworld_plugin_settings', 'wp_helloworld_plugin_settings_nonce'); ?>
                <p>
                    <label for="wp_helloworld_plugin_downloadkey"><?php echo __('Download key', 'wp-helloworld-plugin'); ?></label>
                </p>
                <input type="text" name="wp_helloworld_plugin_downloadkey" id="wp_helloworld_plugin_downloadkey" value="<?php echo esc_attr($downloadKey); ?>" />
            </div>
            <p class="submit">
                <input class="button-primary" name="save" type="submit" value="<?php echo __('Save download key', 'wp-helloworld-plugin'); ?>" />
            </p>
        </form>
    </div>
<?php
}

Now, the user can enter his/hers download key in Settings -> Hello World Plugin.

Sample WordPress plugins and themes

We've put together a WordPress "Hello World" plugin and "Hello World" theme, so you can use them as example to quickly integrate automatic updates to your free or premium plugins and themes using the UpdaterCloud service.