Toplytics

You should use this plugin if you want to display the most visited posts of your site in a safe and stable manner, with no risk of downtime or slowness, based on data from Google Analytics statistics. The plugin is built for high-traffic sites where counting every visitor’s click loads up the DB and can potentially crash the site.

You can set how often the data is refreshed from the widgets settings: hourly, twice a day or daily. By default, it is refreshed hourly.

You also have the possibility to create a custom template. Here it is how.

In toplytics/resorces/views/frontend/ there is a file named widget.template.php, which is the default template. To create a custom template, copy the widget.template.php file here, rename it to custom.template.php and then customize it as you wish. The file is a typical PHP template file.

You can also use the old method of creating a custom template with Toplytics: add a template.php file in your active theme’s root folder.

The priority regarding template files is the following:

• Toplytics will look for a template.php file in the root of the active theme folder – this is to ensure backwards compatibility, as this is how you could create a custom template before; you can still use this option too
• Then it will look for the file custom.template.php in toplytics/resorces/views/frontend/ folder, and if it does not exist, it will display the default template, which is widget.template.php

The shortcode has 3 parameters: period -> default=month (today/week/month), numberposts -> default=5 (min=1/max=250), showviews -> default=false (true/false)

Shortcode example:

[toplytics period="week" numberposts="3" showviews="true"]

The shortcode can be used within post/pages and in other widgets from the sidebar. For any parameter that is not used, the default value will be used.

There is a check in the widget Settings for this operation, called Load via Javascipt AJAX. This way the stats are read from the toplytics.json file or wp-json/toplytics/results (depends on which endpoint you’ve activated) and loaded dynamically with JavaScript. Otherwise, the results will be read from the database.

This can be useful for sites that are using caching, for example. If the top is not loaded dynamically with JavaScript and AJAX, it will not refresh unless someone flushes the page cache.

You can check the JavaScript code on the default template toplytics/resorces/views/frontend/widget.template.php.

This file contains the statistics in JSON format, if you have the custom JSON endpoint enabled. This option exists to maintain backwards compatibility, the recommend option now is to use the REST API Endpoint. This way, your statistics will be retrieved from the endpoint /wp-json/toplytics/results.

After you enable the REST API Endpoint or the custom JSON endpoint, you need to flush the Permalink cache after you change this by visiting Settings > Permalinks and saving that form with no change.

Both the toplytics.json file and the /wp-json/toplytics/results endpoint are designed to be used with the JS custom template code to load the top dynamically with JavaScript and AJAX.

The file toplytics.json is located to the root folder of the site.

Example

If the site domain is http://www.example.com/ then the file url is http://www.example.com/toplytics.json.

The Analytics API only returns the permalink of the posts and the number of pageviews. In order to display the title, as well as other post fields like featured image, post type etc, Toplytics searches your site’s database for these additional information.

However, there are some rare cases when you want to display on your site a top from another site, for example. This means that you don’t have access to the respective site’s database, only to it’s Analytics statistics. In this case, you can activate Skip local posts discovery. This means that instead of searching for additional information in the site’s database, Toplytics will try to generate a human readable title from the URLs that Google Analytics returns. This will only work if you have pretty permalinks enabled for your site’s URLs.

For example, if you have a post with the URL /code/kubernetes-mysql-operator-digital-ocean/, Toplytics will generate the title Code Kubernetes Mysql Operator Digital Ocean.

Along with Skip Local Posts Discovery, you will also need to specify the Custom domain for the site, since Google Analytics doesn’t give us the domain in the URLs it returns. We need the domain to create the links to the articles in the top.

In the Toplytics settings, you have an option called Posts to fetch from GA, which sets up how many articles, pages and other custom post types will be returned by the Google Analytics API.

If you only want your top to show your most viewed posts (not pages or other custom post type), you have a Toplytics setting for specifying what king of posts appear in your top, called Allowed post types. By default it is set to post, which means that it will extract from the data fetched from Google only the posts.

Toplytics will still extract for Google Analytics your 20 most viewed posts and pages for example, but will only display the most viewed posts.

Toplytics fetches from Analytics the number of posts, pages and other post types that you specify on Toplytics Settings -> Posts to fetch from GA, generically called “posts”. Then, they will be filtered based on your Settings. For example, you can set up the Allowed post types, which is set by default to post. In this case, only the posts (articles) will show in your top.

However, you may encounter the following situation. Your most viewed content is your pages, and you only fetch 10 “posts” from Google Analytics. By default, Toplytics displays the most viewed posts (articles), but if the results fetched were all pages, it will have nothing to show. In this case, you can set up a higher number of “posts” to be fetched (the default is 20).

The plugin offers 2 functions that can be used either in the theme or by another plugin. Please review the complete documentation below.

1. toplytics_results

Description

mixed toplytics_results( [ array $args ] )

toplytics_results() prints the toplytics results in <ol> format.

Parameters

args -> This parameter is a list of toplytics options:
period – represents the statistics period, default=month (today/week/month);
numberposts – represents the number of posts to be displayed, default=5 (min=1/max=250);
showviews – set this parameter to true if you want to print out the number of posts views, default=false (true/false);

Return Values

If the toplytics results will be printed, then the function returns TRUE, otherwise the return value is FALSE.

Example

Here is a simple example that displays the first 7 most visited posts in the past month, toghether with the number of views:

<?php
    $toplytics_args = array(
        'period' => 'month',  // default=month (today/week/month)
        'numberposts' => 7,   // default=5 (min=1/max=250)
        'showviews' => true   // default=false (true/false)
    );
    if ( function_exists( 'toplytics_results' ) )
        toplytics_results( $toplytics_args );
?>

2. toplytics_get_results

Description

mixed toplytics_get_results( [ array $args ] )

toplytics_get_results() returns the toplytics results into an array; in this case, the toplytics results’ HTML can be formatted according with your needs.

Parameters

args -> This parameter is a list of toplytics options:
period – represents the statistics period, default=month (today/week/month);
numberposts – represents the number of posts to be displayed, default=5 (min=1/max=250);

Return Values

If the toplytics results contains at least one element, the function will return an array with the toplytics results, otherwise the return value is FALSE.

Example

<?php
    if ( function_exists( 'toplytics_get_results' ) ) {
        $toplytics_args = array(
            'period' => 'month',  // default=month (today/week/month)
            'numberposts' => 3    // default=5 (min=1/max=250)
        );
        $toplytics_results = toplytics_get_results( $toplytics_args );
        if ( $toplytics_results ) {
            $k = 0;
            foreach ( $toplytics_results as $post_id => $post_views ) {
                echo (++$k) . ') <a href="' . get_permalink( $post_id )
                    . '" title="' . esc_attr( get_the_title( $post_id ) ) . '">'
                    . get_the_title( $post_id ) . '</a> - ' . $post_views . ' Views<br />';
            }
        }
    }
?>

The outcome will look like this:

1.) This is the most visited post – 123 Views

2.) This is the second most visited post – 99 Views

3.) This is the third most visited post – 12 Views