Support

Getting Started

How it works

Wisdom has two parts: a code snippet you add to your product that sends data from the remote site where your product is installed, 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 where you wish 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 product you want to track. Depending on your license plan, you can track one product, up to three products, or unlimited products.

Go to Wisdom > My Products. The set up is slightly different depending on whether you are tracking a plugin or a theme.

Tracking plugins

If you are on the one product or three products plans, you will see:

• A field for the website URL where you want to receive data

Then for each product you are tracking:

• There’s a field for the plugin basename (the name of your main plugin file, excluding the file extension)
• A field to track additional options (explained below).

In the example below, I am receiving data at https://wisdomplugin.com/ and the basename for my plugin is wp_test_plugin:

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

Tracking themes

If you’re setting up the code snippet to track a theme, not a plugin:

• Follow the section above but enter your theme name as the ‘Basename’
• Leave the ‘Options’ field empty.

Unlimited products

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

Additional parameters

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

Options

Default: empty

Note that this parameter only applies to plugins, not themes.

You can get deep insight into how your users are working with your plugin by specifying options to track. To use this feature:

• Each option must be saved as an array with the structure $key=>$value (this is how the WordPress Settings API saves options).
• 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 product is not distributed via the WordPress.org repository and you don’t want to ask your users’ permission to track their data.

Include deactivation form

Default: true

Note that this parameter only applies to plugins, not themes.

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 product on their site. Messages are displayed using the standard WordPress notice system.

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

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

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

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

Add the code snippet to your product

Once you’ve generated the code snippet, add it as follows:

Plugins

Copy the snippet and paste it at the bottom of your plugin’s main file. (What is the main plugin file?)

Themes

Copy the snippet and paste it at the bottom of your theme’s functions.php file

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

Distribute your product

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

Monitoring your products

My Reports

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

Summary: This provides you with a quick overview of the number of products you’re tracking over how many sites. It displays the number of active and deactivated products and gives you a handy deactivation rate. You can drill down in this report to focus on specific products, 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 product then compare those times across versions. Have you fixed a bug 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 products, and the type of chart – either doughnut or bar.

Mailchimp

You can enter your Mailchimp API key in Wisdom > Settings. You can then choose which of your Mailchimp lists to automatically add users to. If you are tracking more than one product, you can specify different lists for each product. You can even specify simple rules to add users to different lists according to conditions – e.g. add a user to a specific list if they are running a certain plugin on their site. In the screenshot below, users who have Easy Digital Downloads installed get added to a specific list. Define the plugin or theme using its slug.

Advanced

Filter notification text

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

You can use the following filter to change the message, which must be placed in your main plugin file or theme functions.php 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_' . basename( __FILE__, '.php' ), 'your_prefix_notification_text' ); // Must be added to your main plugin file

Delaying the notification

You may wish to delay showing the user the opt-in notice as soon as they activate the plugin. Perhaps you already have notices to display to the user. If so, just do this in your main plugin file:

function your_prefix_delay_notification( $delay ) {
 return 3600; // Enter a value here in seconds
}
add_filter( 'wisdom_delay_notification_' . basename( __FILE__, '.php' ), 'your_prefix_delay_notification' );

The example above will delay the opt-in notification for one hour.

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_’ .basename( __FILE__, '.php' ), ‘your_prefix_filter_deactivation_form’ ); // Must be added to your main plugin file

This snippet should be added to your main plugin file.

Opting in or out after activation

You might like to allow your users to change their mind after they’ve opted in. To do this on plugins, 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.

To allow users to change their minds in a theme, you must include a theme mod called wisdom-allow-tracking. If this option is deselected, the theme will no longer send tracking data.

Your users will then have a checkbox they can use to change their mind about tracking even if they initially opted in.

Exporting your data

Wisdom allows you to export your data to a CSV file. Click on Wisdom > Export and select the parameters you wish to export. Click the ‘Export to CSV’ button to export the file.

Extending Wisdom

You can extend Wisdom using its available hooks:

wisdom_create_new_item – runs when a new site is recorded on your base site

wisdom_deactivate_existing_item – runs when a product is deactivated

Available parameters

$post_params includes the following arguments:

url
product_type
plugin_slug
site_name
site_version
site_language
text_direction
charset
plugin
status
version
theme
theme_version
theme_parent
first_recorded
deactivated_date
deactivation_reason
deactivation_details
message
file_location
wisdom_version
php_version
server
multisite
email
marketing_method
active_plugins
inactive_plugins
plugin_options
plugin_options_fields

Troubleshooting

Local sites not tracking

Wisdom doesn’t track local installations.

Questions?

Any questions, just get in touch.