How to use Toplytics

Toplytics the widget

Toplytics displays the most visited posts as a widget from the Appearance -> Widgets page. Simply drag-and-drop your newly available Toplytics widget wherever you want to display it.

You can set up:

• the title of your top
• the number of posts to show in your top
• the statistics period, this means to choose if you want to display your most visited posts per month, week or day
• if you want to display post views
• if you want to Load via JavaScript AJAX, see How can I use JavaScript code to show up the top .

The widget also tells you which template you are using, for more information check How to use the custom template .

You can now visualize your most visited posts. Here is an example of using Toplytics on www.homedit.com :

FAQ

Why should I use this plugin?

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.

I’ve updated Toplytics and it’s not working anymore

How often is the data from Google Analytics refreshed?

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.

How to use the custom template?

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.blade.php, which is the default template. To create a custom template, copy the widget.blade.php file here, rename it to custom.blade.php and then customize it as you wish. The file is a typical blade PHP template file, but this does not restrict you from using plain PHP code in it if you are not familiar with the Laravel framework.

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.blade.php in toplytics/resorces/views/frontend/ folder, and if it does not exist, it will display the default template, which is widget.blade.php

How can I use the shortcode?

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.

How can I use JavaScript code in order to show up the top in widget?

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.blade.php.

What is toplytics.json file?

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.

NOTE

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 .

Where is toplytics.json file located?

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

Example

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

What is Local Post Discovery?

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.

Why are pages showing up in my Toplytics Most Viewed Posts 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.

Why is my Toplytics output empty?

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).

How can I use the plugin functionality outside the sidebar?

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

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

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