Examples of using google analytics

examples/google-analytics/README.md

@@ -0,0 +1,55 @@
+# Google Analytics
+
+These examples show how to read data via [googleanalytics adapter](https://github.com/juttle/juttle-googleanalytics-adapter)
+from a Google Analytics account (in this case, pageviews data for a website),
+process the metrics in juttle, and visualize using juttle-viz charts. 
+
+You can view these examples on the demo system [demo.juttle.io](http://demo.juttle.io/?path=/examples/google-analytics/index.juttle), or run them on your own using docker (see the parent [README](../README.md)).
+
+[This blog post](XXX) describes the analysis of pageviews data by browser version, and the conclusions drawn from it.
+
+## Additional docker-compose configuration
+
+None needed.
+
+## ``juttle-config.json`` configuration
+
+Modify `juttle-config.json` to add a ``googleanalytics`` section containing credentials to access messages via the Google Analytics API.
+
+The [googleanalytics adapter README](https://github.com/juttle/juttle-googleanalytics-adapter) explains how to obtain the creds.
+
+{
+    "adapters": {
+        "googleanalytics": {
+            "service_account": {
+                "type": "service_account",
+                "project_id": "<YOUR PROJECT ID>",
+                "private_key_id": "<YOUR PROJECT KEY ID>",
+                "private_key": "-----BEGIN PRIVATE KEY-----\n<YOUR PRIVATE KEY>\n-----END PRIVATE KEY-----\n",
+                "client_email": "<YOUR ACCOUNT EMAIL>",
+                "client_id": "<YOUR CLIENT ID>",
+                "auth_uri": "https://accounts.google.com/o/oauth2/auth",
+                "token_uri": "https://accounts.google.com/o/oauth2/token",
+                "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
+                "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/<YOUR ACCOUNT EMAIL>"
+            }
+
+        }
+    }
+}
+
+## Juttle Programs
+
+To run any of these programs, just visit
+``http://(localhost|docker machine ip):8080/?path=/examples/google-analytics/index.juttle``
+and follow the links.
+
+`browser_versions_recent.juttle` reads pageviews data from Google Analytics for a selected recent time period,
+aggregated by browser type, browser version (which is a complete version string with major and minor numbers),
+and device category (desktop, mobile or tablet). Then it computes major version to aggregate by that,
+and visualizes the data as piecharts and tables for each common browser.
+
+`browser_versions_over_time.juttle` reads pageviews data for an entire last year and visualizes the browser version
+breakdown over time, on a timechart, for a selected browser type and desktop vs mobile platform. For completeness,
+it also present the last month's data for the same browser as a piechart and a table.
+

examples/google-analytics/browser_helper.juttle

@@ -0,0 +1,26 @@
+// Helper module with common subs
+
+// In addition to supplying the website name as an input,
+// a matching Google Analytics account must be defined in juttle config.
+//
+export input site: text -label 'Website tied to your Google Analytics account:' -default 'www.jut.io';
+
+// Take categories contributing less than x percent to the total and
+// group them together in an "Other" category.
+//
+export sub threshold(thresh, every=null) {
+  (reduce -every every total=sum(value); pass)
+  | join
+  | put pct = 100.0*value/total
+  | put name=(pct >= thresh ? name : 'other')
+  | reduce -every every value=sum(value) by name
+}
+
+// Convert raw values to percentages of the total.
+//
+export sub percentages(scale=100, every=null) {
+  ( reduce -every every total = sum(value); pass)
+  | join
+  | put value = Math.round(value * scale / total, 2)
+  | remove total
+}

examples/google-analytics/browser_versions_over_time.juttle

@@ -0,0 +1,63 @@
+// Read, process, visualize pageviews data from Google Analytics
+// Breakdown by browser version over time is displayed as timechart,
+// more recent data on piechart and in a table.
+
+import './browser_helper.juttle' as h;
+
+// Define deviceCategory and browser type inputs
+//
+const devices = {
+  'desktop': ['desktop'],
+  'mobile or tablet': ['mobile', 'tablet'],
+  'all': ['desktop', 'mobile', 'tablet']
+};
+input bro: select -label 'Which browser:' -default 'Chrome'
+  -items [ 'Chrome', 'Safari', 'Firefox', 'Internet Explorer' ];
+input dev: select -label 'Desktop or mobile:' -default 'all'
+  -items Object.keys(devices);
+
+// No point in defining an input for website
+// since juttle config must contain the Google Analytics account
+// that is tied to this specific website anyway.
+//
+const site = 'www.jut.io';
+
+// read weekly pageviews for last year, visualize on timechart
+// Note: reading a year's worth of data from GA takes many seconds!
+// Repeated runs are faster due to caching on GA side.
+//
+read googleanalytics -from :today:-:1 year: -to :now: -webProperty site
+| reduce -every :week: views = sum(pageviews) by browser, browserVersion, deviceCategory
+| filter browser = bro AND deviceCategory in devices[dev]
+| put majorVersion = String.split(browserVersion, '.')[0]
+| put name = majorVersion, value = views
+| h.threshold -thresh 5 -every :week:
+| h.percentages -every :week:
+| view timechart
+  -title "Rise and fall of ${bro} versions over time (devices: ${dev}, last 1 year)"
+  -series [{ name: 'other', color: 'white' }] -seriesLimit 50
+  -keyField 'name' -markerSize 5 -interval :2w:
+  -yScales.primary.label '% pageviews' -row 0 -col 0;
+
+// read last month's pageviews, visualize as piechart and table
+//
+read googleanalytics -from :today:-:1 month: -to :now: -webProperty site
+| reduce views = sum(pageviews) by browser, browserVersion, deviceCategory
+| filter browser = bro AND deviceCategory in devices[dev]
+| put majorVersion = String.split(browserVersion, '.')[0]
+| put name = "v${majorVersion}", value = views
+|(
+  h.threshold -thresh 5
+  | h.percentages -scale 1
+  | view piechart -title "Common versions of ${bro} (devices: ${dev}, last 1 month)"
+    -radiusInner 42 -sliceLabels.valueFormat '%'
+    -row 1 -col 0;
+
+  h.percentages -scale 100
+  | filter value > 1
+  | sort majorVersion -desc
+  | keep majorVersion, value
+  | view table -title "Pageview % by ${bro} version (last 1 month)"
+    -columnOrder 'majorVersion', 'value'
+    -row 1 -col 1;
+  )

examples/google-analytics/browser_versions_recent.juttle

@@ -0,0 +1,85 @@
+// Read, process, visualize pageviews data from Google Analytics
+// Breakdown by browser type is displayed in piecharts / tables
+
+import './browser_helper.juttle' as h;
+
+const intervals = {
+  '1 day': :1 day:,
+  '1 week': :1 week:,
+  '2 weeks': :2 weeks:,
+  '1 month': :1 month:,
+  '6 months': :6 months:
+};
+input i: select -label 'Choose time period for pageviews: '
+  -items Object.keys(intervals) -default '1 week';
+
+const start = :today: - intervals[i];
+const site = 'www.jut.io';
+const label = 'on ${site} over the last ${intervals[i]}';
+
+// Show pageviews % by browserVersion for a given browser
+// in a piechart and a table.
+// Uncommon versions get combined into 'Other' category.
+sub browser_version_usage(browser_name, row_num) {
+  put majorVersion = String.split(browserVersion, '.')[0]
+  | reduce value = sum(pageviews) by browser, majorVersion, deviceCategory
+  |(
+    put name = browser+'-'+majorVersion+'.'+deviceCategory
+    | h.threshold -thresh 3
+    | h.percentages -scale 1.00
+    | view piechart -title "Common versions of ${browser_name} ${label}"
+      -radiusInner 42 -sliceLabels.valueFormat '%'
+      -row row_num -col 0;
+
+    h.percentages -scale 100
+    | filter value > 1
+    | sort browser, majorVersion -desc, deviceCategory
+    | view table -title "Pageview % by version of ${browser_name}"
+      -columnOrder 'browser', 'majorVersion', 'deviceCategory', 'value'
+      -row row_num -col 1  -height 1000;
+  )
+}
+
+// Show pageviews % by browser type in a piechart and a table.
+// Uncommon browsers get combined into 'Other' category.
+sub browser_usage(row_num) {
+  put majorVersion = String.split(browserVersion, '.')[0]
+  | reduce value = sum(pageviews) by browser, deviceCategory
+  |(
+    put name = browser+'-'+deviceCategory
+    | h.threshold -thresh 2
+    | h.percentages -scale 1.00
+    | view piechart -title "Common browser types ${label}"
+      -radiusInner 42 -sliceLabels.valueFormat '%'
+      -row row_num -col 0;
+
+    h.percentages -scale 100
+    | filter value > 1
+    | sort browser, deviceCategory
+    | view table -title "Pageview % by browser type"
+      -columnOrder 'browser', 'deviceCategory', 'value'
+      -row row_num -col 1;
+  )
+}
+
+
+emit | put description = '# Pageviews ${label}'
+| view markdown -row 0;
+
+emit | put description = '## Breakdown of pageviews per browser ${label}'
+| view markdown -row 2;
+
+read googleanalytics -from start -to :now: -webProperty site
+| reduce pageviews=sum(pageviews) by browser, browserVersion, deviceCategory
+|(
+  browser_usage -row_num 1;
+
+  filter browser = 'Chrome'
+  | browser_version_usage -browser_name 'Chrome' -row_num 3;
+  filter browser = 'Firefox'
+  | browser_version_usage -browser_name 'Firefox' -row_num 4;
+  filter browser = 'Safari'
+  | browser_version_usage -browser_name 'Safari' -row_num 5;
+  filter browser = 'Internet Explorer'
+  | browser_version_usage -browser_name 'Internet Explorer' -row_num 6;
+)

examples/google-analytics/index.juttle

@@ -0,0 +1,11 @@
+sub add_juttle(name, description) {
+    put program="[${name}](/?path=/examples/google-analytics/${name}.juttle)", description=description
+}
+
+emit 
+|( 
+  add_juttle -name "browser_versions_recent" -description 'Show site pageviews by version for common browsers';
+  add_juttle -name "browser_versions_over_time" -description 'Show site pageviews by version over time for a given browser';
+)
+| keep program, description
+| view table -title "Demo Juttle Programs" -markdownFields ['program']