diff --git a/examples/google-analytics/README.md b/examples/google-analytics/README.md new file mode 100644 index 0000000..f3aaa7b --- /dev/null +++ b/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": "", + "private_key_id": "", + "private_key": "-----BEGIN PRIVATE KEY-----\n\n-----END PRIVATE KEY-----\n", + "client_email": "", + "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/" + } + + } + } +} + +## 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. + diff --git a/examples/google-analytics/browser_helper.juttle b/examples/google-analytics/browser_helper.juttle new file mode 100644 index 0000000..5cff698 --- /dev/null +++ b/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 +} diff --git a/examples/google-analytics/browser_versions_over_time.juttle b/examples/google-analytics/browser_versions_over_time.juttle new file mode 100644 index 0000000..2766532 --- /dev/null +++ b/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; + ) diff --git a/examples/google-analytics/browser_versions_recent.juttle b/examples/google-analytics/browser_versions_recent.juttle new file mode 100644 index 0000000..d938291 --- /dev/null +++ b/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; +) diff --git a/examples/google-analytics/index.juttle b/examples/google-analytics/index.juttle new file mode 100644 index 0000000..61d69f2 --- /dev/null +++ b/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']