Top
The top block helper allows for downloading the most viewed posts from Google Analytics.
Note that top is an async helper.
This page shows you how to use the helper. If you are interested in how and why I created it, you can read my blog post about this helper.
First, you have to set up a service account that can be authenticated and authorized to the Google Analytics API. This part is actually kind of tricky (the irony is that no matter how much I've serched with Google for a comprehensive but simple tutorial on how to this, I couldn't find any).
- Go to console.developer.google.com and sign in with the account that owns the Google Analytics account.
- Create a new project (this is fairly simple, you just have to specify a name).
- On the project dashboard, select 'ENABLE APIS AND SERVICES'.
- Type 'Analytics' into the searchbox and then enable the Google Analytics Reporing API and the Analytics API (just click on the search result and on the details page, simply press the button).
- Go back to the dashboard and choose the Credentials option.
- Choose 'Create credentials' and then 'Service account key'.
- Choose a name for your service account. For the 'Role', select 'Project', then 'Viewer'. Finally, select the JSON option and download the file containing the account information. Be sure to keep this somewhere safe, because the information in it cannot be recovered later.
- Go to your Google Analytics account and chose the Admin option (bottom left corner).
- Choose the property to which you want to download data for (i.e. your website) and the view you want to download data from. In the example, the default 'All website data' is used.
- From the View Settings blade, get the View ID.
- On the User management blade, add a new user.
- Specify the e-mail address of the service account (you can get that from the JSON file you downloaded in step 7). Choose 'Read & Analyze' for the permission.
- For the next steps, you'll need the View ID from step 9, and "client_email" and the "private_key" values from the JSON file downloaded in step 7.
- Set the GA_CLIENT_EMAIL environment variable to the value of "client_email", and the GA_PRIVATE_KEY environment variable to the value of "private_key" from the previous step. You'll need the viewId when actually using the helper, as shown in the Examples section.
- interval : optional, string This allows for specifying the analysis interval (i.e. download the top pages from the last week or last year). The possible values are 'allTime', 'thisYear', 'thisMonth' or 'thisWeek'. The default is 'allTime'.
- maxItems : optional, number The number of top items to download. The default is 10.
- viewId : required, string The ViewId to download data from.
The helper issues a properly constructed request to the Google Analytics API to download the most viewed posts from the view specified by the viewId parameter with the authorization information set up in the proper environment variables. The query is constructed so that it excludes:
- Pages that have no title set
- The main page (the url is /)
- Pages that are used for pagination (the url contains /page/ )
- Pages that are tag pages (the url contains /tag/)
- Pages whose url contains the '&' character (these are most likely spam requests) Inside the block helper, you can use the posts property to foreach over inside the top helper (just like you'd do with the built-in get helper). Inside the foreach, you can use the usual post attributes and an additional viewCount property that contains the number of views for the post in the given interval.
This snippet downloads this week's most viewed 10 posts and outputs links to them.
{{#top viewId = '123456789' interval = 'allTime' maxItems=10}}
{{#foreach posts}}
<a href="{{url}}">{{title}} ({{viewCount}})</a>
{{/foreach}}
{{/top}}