Support

It’s pretty simple to get Wisdom up and running. This page will take you through it step by step.

  • Getting started
    • How it works
    • Install Wisdom
    • Enter the license key
    • Generate the code snippet
    • Add the code snippet to your plugin
    • Distribute your plugin
  • Monitoring your plugins
    • Reports
    • Custom Reports
    • Email Addresses
  • Advanced
    • Filter notification text
    • Filter deactivation form
    • Opt out setting
  • Troubleshooting / Things to watch out for
    • Local sites not tracking
    • Questions?

Getting Started

How it works

Wisdom has two parts: a code snippet you add to your plugin to send data, and a plugin you install on your site to receive data. Add the code snippet and class to your plugin and it will handle all the user opt-in stuff as well as sending data to your site.

Install Wisdom

The first step is to install the Wisdom plugin to the site you wish to use to receive data. The Wisdom plugin is one of the files you download from this site when you make a purchase.

To install, follow the standard WordPress steps:

  1. In your dashboard, go to Plugins > Add New
  2. Click the ‘Upload Plugin’ button
  3. Upload the wisdom-plugin.zip file you just downloaded
  4. Activate

Enter the license key

When activated, Wisdom will add a new menu item to your dashboard. Click Wisdom > License and enter your license key in the field. Click Save to save the key, then click Activate License to activate it.

Generate the code snippet

Once you’ve activated your license, you can generate the code snippet for each plugin you want to track. Depending on your license plan, you can track one plugin, up to three plugins, or unlimited plugins.

Go to Wisdom > My Plugins. If you are on the one plugin or three plugins plans, you see a field for the website URL where you want to receive data then, for each plugin you are tracking, there’s a field for the plugin slug and some additional options (explained below). In the example below, I am receiving data at https://wisdomplugin.com/ and the slug for my plugin is wp-test-plugin:

Enter your details and click ‘Save Changes’. Your code snippet will be generated:

Note that it’s important to use the code snippet exactly as it’s generated in order to avoid any conflicts with other plugins that might be using this same system.

If you have a plan to track an unlimited number of plugins, the My Plugins screen will look slightly different. You will need to enter the URL of the site receiving data, the plugin slug, and the other options then click ‘Get Snippet’ to generate the code. Repeat this and the next step for every plugin you’re tracking.

You will notice some additional parameters that you can set. These are:

Options

Default: empty

You can get deep insight into how your users are working with your plugin by specifying options to track. To use this feature, your plugin must be using the Settings API to register settings, each option must be saved as an array, and each option must contain an element with the key wisdom_registered_setting set to the value 1. A typical way to ensure this is to include the setting as part of the default values that are set when the plugin is activated.

You should enter settings as a comma-separated list in this field, e.g:

my_plugin_general_settings, my_plugin_style_settings

Require opt-in

Default: true

Set this parameter to false if your plugin is not distributed via the WordPress.org plugin repository and you don’t want to ask your users’ permission to track their data.

Include deactivation form

Default: true

Set this parameter to false if you don’t want to present a feedback form to users when they deactivate your plugin.

Notification message

Default: Option 1

This defines the message displayed to the user when they first install and activate your plugin on their site. Messages are displayed using the standard WordPress notices.

Option 0 presents a single message to the user as follows:

Thank you for installing our plugin. We would like to track its usage on your site. We don’t record any sensitive data, only information regarding the WordPress environment and plugin settings, which we will use to help us make improvements to the plugin. Tracking is completely optional.

Option 1 presents a single message to the user as follows:

Thank you for installing our plugin. We’d like your permission to track its usage on your site and subscribe you to our newsletter. We won’t record any sensitive data, only information regarding the WordPress environment and plugin settings, which we will use to help us make improvements to the plugin. Tracking is completely optional.

Option 2 presents two separate notices for opting in to tracking and to email collection, as follows:

Thank you for installing our plugin. We would like to track its usage on your site. We don’t record any sensitive data, only information regarding the WordPress environment and plugin settings, which we will use to help us make improvements to the plugin. Tracking is completely optional.

Then, if the user opts in to tracking, they receive a second notice:

Thank you for opting in to tracking. Would you like to receive occasional news about this plugin, including details of new features and special offers?

Add the code snippet to your plugin

Once you’ve generated the code snippet, copy it and paste it at the bottom of your plugin’s main file. (What is the main plugin file?)

You will also need to add the ‘tracking’ folder to your plugin folder. The ‘tracking’ folder is contained in ‘tracking.zip’ that you downloaded with the ‘wisdom.zip’ plugin files. Unzip ‘tracking.zip’ and place the folder in the top level of your plugin folder.

Remember that if you are tracking more than one plugin, you need to ensure you have generated a unique snippet for each plugin. You can only do this by entering a unique slug for each plugin you are tracking.

Distribute your plugin

If you’ve followed the steps above correctly, you should now be ready to distribute your plugin. We strongly recommend, however, that you test the tracking code before you release your plugin publicly.

Monitoring your plugins

My Reports

Currently, the following reports are available from the Wisdom dashboard:

Summary: This provides you with a quick overview of the number of plugins you’re tracking over how many sites. It displays the number of active and deactivated plugins and gives you a handy deactivation rate. You can drill down in this report to focus on specific plugins, if you’re tracking more than one, and include start and end date parameters.

Activations over Time: View how many activations and deactivations have taken place across a specified time period. This is useful for seeing sudden spikes or drops in activations and deactivations, for instance when you’ve released a new version.

Deactivation Reasons: When users deactivate your plugin, they are presented with a form that allows them to say why they’ve chosen to activate. The Deactivations Report collates these reasons and allows you to identify where the pain points are for your users: maybe documentation isn’t up to scratch or users aren’t finding the features they’re expecting? You can drill down by plugin and date.

Deactivations Time and Version: Track the average time users take to deactivate your plugin then compare those times across versions. Have you introduced a bug fix in a recent version? This report should show you where the improvements have occurred.

Custom Reports

This page allows you to generate reports for most of the tracked parameters. You can specify time periods, individual plugins, and the type of chart – either doughnut or bar.

Email Addresses

If you’ve chosen to collect admins’ email addresses, you can run a query from this page to identify all email addresses collected within date parameters. If you’re tracking multiple plugins, the email addresses are organized by plugin so you can add them to different lists if you need to.

Advanced

Filter notification text

The notification is displayed to users when they first activate your plugin. It requests permission to track the plugin. It always displays the name of the plugin first then a filterable message.

You can use the following filter to change the message, which must be placed in your main plugin file. Please note that you must ensure that you clearly state that tracking is optional if you are distributing your plugin on the WordPress.org repository.

function your_prefix_notification_text( $notice_text ) {
  $notice_text = __( ‘Your message here', 'your-text-domain' );
  return $notice_text;
}
add_filter( ‘wisdom_notice_text' . __FILE__, 'your_prefix_notification_text' ); // Must be added to your main plugin file

Filter deactivation form

You can filter all content within the form that displays to the user if they deactivate your plugin. An example function is below – ensure you include all elements:

function your_prefix_filter_deactivation_form( $form ) {
  
$form[‘heading’] = __('Sorry to see you go', 'your-text-domain' );
  $form['body'] = __('Before you deactivate the plugin, would you quickly give us your reason for doing so?', 'your-text-domain' );
  $form['options'] = array(
    __('Set up too difficult', 'your-text-domain' ),
    __('Not the features I wanted', 'your-text-domain' ),
    __('Found a better plugin', 'your-text-domain' )
  );

  return $form;
}

add_filter( ‘wisdom_form_text_’ . __FILE__, ‘your_prefix_filter_deactivation_form’ ); // Must be added to your main plugin file

This snippet should be added to your main plugin file.

Opt out setting

You might like to allow your users to change their mind after they’ve opted in. To do this, you need to ensure that you add a checkbox setting with the name wisdom_opt_out to your options. The wisdom_opt_out setting must belong to one of the options you have included in the snippet code.

Your users will then have a checkbox they can select to opt out of tracking even if they initially opted in.

Troubleshooting

Local sites not tracking

Wisdom doesn’t track local installations.

Questions?

Any questions, just get in touch.