Japanese Document

Japanese Document (my blog's article) is following
- Google Analytics の API を用いて簡単にデータを取得できる gem を作りました

What's this?

This gem helps you to obtain Google Analytics reporting data with ease.

First of all, you create configuration YAML file as Google Analytics API. Then execute the simple Ruby code, and you obtain Google Analytics reporting data.

Yeah, very simple :)

Wrapper gem of Legato

This gem is a wrapper of Legato gem. Legato is very coooooooool and full-stack gem, so complicated as a beginner (me!).

Therefore I developed this wrapper gem, simple_ga_reporting.

Get Started

1. Installation

$ gem install simple_ga_reporting

2. Set `private_key` and `client_email`

There are two ways to set private_key and client_email
How to get above two Key-Value sets is written later

2-1. The first way: Create API configuration file

Create ./config/key_and_email.yml
This YAML file must contain two Key-Value sets
- private_key and its value
- client_email and its value

2-2. The second way: Set values as arguments

Set arguments of SimpleGaReports.filtered_results method
For example:
- SimpleGaReports.filtered_results(private_key: 'FOO', client_email: 'BAR')
Convenient when you set by environment variables

3. Create Google Analytics reporting configuration file

You must create the YAML file which contains Google Analytics reporting configuration such as start-date, end-date, metrics, demensions, filters and etc.
filepath is ./config/ga_reporting_config.yml
This YAML file format is shown later

4. Create filters file (Optional)

If you wanna use filters function, please create ./config/filters.rb
the filters configuration on GUI is below

filter configuration on GUI

5. Write your app

Write your application used this gem
The sample code is below
- Use only two class methods
  - SimpleGaReports.configure
  - SimpleGaReports.filtered_results
- Only three lines :-)
- Note
  - If you don't use filters, use SimpleGaReports.raw_results too
  - when no filter is in configure file, SimpleGaReports.raw_results is the same as SimpleGaReports.filtered_results

require 'simple_ga_reporting'

SimpleGaReports.configure
SimpleGaReports.filtered_results #=> Legato::Query

Detail of configuration

1. Configuration of API account

You must set Google Analytics API configuration, private_key and client_email
There are two ways to set it
- The one is by arguments
  - Set arguments of SimpleGaReports.filtered_results method
- The other is by YAML file
  - Default filepath is ./config/key_and_email.yml
  - You can change filepath by argument
The sample of YAML file is below

private_key: "-----BEGIN PRIVATE KEY-----\nMIIE..........Eqw==\n-----END PRIVATE KEY-----\n"
client_email: "[email protected]"

2. Google Analytics reporting configuration

You must create the YAML file which contains Google Analytics reporting configuration
Default filepath is ./config/ga_reporting_config.yml
- You can change filepath by argument in SimpleGaReports.configure method
The sample of YAML file is below

profile_name: my_profile_name
start_date: 2018-04-01
end_date: 2018-04-05
metrics:
  - users
  - pageviews
dimensions:
  - pagePath
  - pageTitle
sort:
  - -pageviews
  - -users
filters:
  - my_awesome_filter
  - his_awesome_filter
  - her_awesome_filter
limit: 20

Please refer the official documents as Key-Value sets
- https://developers.google.com/analytics/devguides/reporting/core/v3/reference

Though above official documents show many Key-Value sets, you can config only several sets as below
- start-date
- end-date
- metrics
- dimensions
- sort
- filters
- max-results
- samplingLevel
Some Key names in configure file are different from ones in official document
- start_date in configure file (not start-date)
- end_date in configure file (not end-date)
- limit in configure file (instead of max-results)
- sampling_level in configure file (not samplingLevel)
The type of metrics, dimensions, sort and filters is Array
- The order of elements doesn't matter

2-1. Key-Value detail

profile_name

REQUIRED
It was called view (view name) before
- but in Japanese page, still ビュー名

View or Profile

start_date

REQUIRED
Original Key name is start-date
Value examples
- 2018-04-01
- today or yesterday
- 14daysAgo
  - use daysAgo phrase even if 1day

end_date

REQUIRED
Original Key name is end-date
Value examples are the same as start-date

metrics

REQUIRED
指標 in Japanese
Official documents are below (very useful!)
- Dimensions & Metrics Explorer
Value examples
- users
- uniquePageviews

Dimensions & Metrics Explorer

dimensions

optional
Official documents are below (very useful!)
- Dimensions & Metrics Explorer
Value examples
- pagePath
- sessionCount

sort

optional
prefix
- - sign means descending
- no sign means ascending
  - Don't use + sign
Value examples
- -pageviews
- users

filters

optional
Value is method name you named in filters.rb

limit

optional
Original Key name is max-results
Value is max amount of returned rows
Default value is 100

sampling_level

optional
Original Key name is samplingLevel
Default value is HIGHER_PRECISION

3. filters file

You use filters function using filters.rb file
- the filename filters.rb is determined
  - only filepath is optional
- the module name Filters is determined
- Default filepath is ./config/filters.rb
  - You can change it by argument with configure method
Examples

module Filters
  def chrome_or_fx
    filter :chrome_or_fx, &lambda { contains(:browser, 'Chrome|Firefox') }
  end

  def awesome_page
    filter :awesome_page, &lambda { contains(:pagePath, '\A.*awesome.*\z') }
  end
end

chrome_or_fx method filters the results
- pick up data which contains 'Google Chrome' or 'Firefox' as browser
the convention of filter method is below
- define method name
- define filter name by symbol which is the same as method name
- define filter behavior by block object
Usage of multiple filters
- If you want to apply AND-chain, only specify each filter in Google Analytics reporting configuration file
- If you want to apply OR-chain, use regexp in block object as chrome_or_fx method
Adding refer Legato's Documents

Arguments of method

Note

YOU MUST SPECIFY ARGUMENTS AS RELATIVE FILEPATH SO YOU MUST ADD './' (dot slash) AT BEGINNING

Set arguments of SimpleGaReports.filtered_results method
For example:
- `SimpleGaReports.filtered_results(private_key: 'FOO', client_email: 'BAR')
Convenient when you set by environment variables

`SimpleGaReports.filtered_results` method

If you don't use filters, use SimpleGaReports.raw_results method instead of SimpleGaReports.filtered_results method
- when no filter is in configure file, SimpleGaReports.raw_results is the same as SimpleGaReports.filtered_results
take three arguments
- All arguments are keyword ones
- You must set (key_and_email_file) or (private_key and client_email)

key_and_email_file
- default is ./config/key_and_email.yml
private_key
- default is nil
client_email
- default is nil

`SimpleGaReports.configure` method

take three arguments
- All arguments are keyword ones

report_config
- first argument
- YAML file
- default is ./config/ga_reporting_config.yml
filters
- second argument
- filter file
- default is ./config/filters.rb
**options
- third argument
- default is nil
- if you set this argument, you can overwrite values in Google Analytics reporting configuration file
- example
  - start_date: '90daysAgo', end_date: '60daysAgo', limit: 100

How to get `private_key` and `client_email`

1. Access to Google Cloud Platform Console

2. Create new project

name new project as you like

3. Create service account for Google Analytics API and select `API and Service` from menu

Google Cloud Platform API menu

4. Create authentication information

Select Service Account Key

Google Cloud Platform API Auth Info

5. Select Service Account and download JSON Key

Google Cloud Platform JSON Key

6. Open JSON Key file by editor and pick up `"private_key"` and `"client_email"`

Google Cloud Platform private_key and client_email

7. They are the very Key-Value sets you want

Deal with them carefully

8. They are the very Key-Value sets you want

Deal with them carefully

9. Activate Analytics API

NOT Google Analytics Reporting API BUT Analytics API

GCP Activate API 01

GCP Activate API 02

GCP Activate API 03

10. Add API user to Google Analytics

In Google Analytics, add mail address of API user
Only Display and Analytics authority needs

Sample App

Note

YOU MUST SPECIFY ARGUMENTS AS RELATIVE FILEPATH SO YOU MUST ADD './' (dot slash) AT BEGINNING

Prepare files

./my_sample_app.rb
./foo/my_key_and_email.yml
./bar/my_ga_reporting_config.yml
./foobar/filters.rb

1. `./my_sample_app.rb`

require 'simple_ga_reporting'

SimpleGaReports.configure(report_config: './bar/my_ga_reporting_config.yml', filters: './foobar/filters.rb', start_date: '2daysAgo', limit: 100)
results = SimpleGaReports.filtered_results(key_and_email: './foo/my_key_and_email.yml') # or use arguments of 'private_key:' and 'client_email:'

results.each do |result|
  puts '==================================='
  puts result['pagePath']
  puts result['pageTitle']
  puts result['pageviews']
  puts result['users']
end

2. `./foo/my_key_and_email.yml`

private_key: "-----BEGIN PRIVATE KEY-----\nMIIE..........Eqw==\n-----END PRIVATE KEY-----\n"
client_email: "[email protected]"

You can set two key and value by not only YAML file but also arguments of SimpleGaReports.filtered_results method

3. `./bar/my_ga_reporting_config.yml`

profile_name: my_profile_name
start_date: 2018-04-01
end_date: 2018-04-05
metrics:
  - users
  - pageviews
dimensions:
  - pagePath
  - pageTitle
sort:
  - -pageviews
  - -users
filters:
  - chrome_or_fx
  - happy_page
limit: 20

4. `./foobar/filters.rb`

module Filters
  def chrome_or_fx
    filter :chrome_or_fx, &lambda { contains(:browser, 'Chrome|Firefox') }
  end

  def happy_page
    filter :happy_page, &lambda { contains(:pagePath, '\A.*happy.*\z') }
  end
end

execute script

$ ruby ./my_sample_app.rb
===================================
/i_am_happy.html
I am HAPPY!
10000
1000
===================================
/happy/index.html
HAPPY TOP
9000
900
===================================
/path/to/happy.html
Are You Happy?
8000
800
===================================
/happy.php
HAPPY CHECK!
7000
700
===================================
......

Rails

When you use this gem on Rails, it's simple :)

add this gem to Gemfile
$ bundle install
after it, the same way above

Very Awesome Reference Book (Recommended)

わかばちゃんと学ぶ Googleアナリティクス (Let's study Google Analytics with Wakaba-Chan)

わかばちゃんと学ぶ Googleアナリティクス

Created by Ai Minatogawa
- She is an energetic creator!
Japanese version only
- English version will...?

Official documents

Core Reporting API - Reference Guide

https://developers.google.com/analytics/devguides/reporting/core/v3/reference

Dimensions & Metrics Explorer

https://developers.google.com/analytics/devguides/reporting/core/dimsmets

Query Explorer

https://ga-dev-tools.appspot.com/query-explorer/

API Rate Limits

https://developers.google.com/analytics/devguides/reporting/core/v3/limits-quotas

TODO

can input not only profile_name but also profile id (view id)
implement following query parametes
- offset
- quota_user
- segment_id
  - ~~segment is the same as conbination of filters, so you can use 'filters' as alternative way~~
  - segment is the first filter for initial population and it can't substitute

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/corselia/simple-ga-reporting. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

License

The gem is available as open source under the terms of the MIT License.

Code of Conduct

Everyone interacting in the SimpleGaReporting project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.

Japanese Document

What's this?

Wrapper gem of Legato

Get Started

1. Installation

2. Set private_key and client_email

2-1. The first way: Create API configuration file

2-2. The second way: Set values as arguments

3. Create Google Analytics reporting configuration file

4. Create filters file (Optional)

5. Write your app

Detail of configuration

1. Configuration of API account

2. Google Analytics reporting configuration

2-1. Key-Value detail

profile_name

start_date

end_date

metrics

dimensions

sort

filters

limit

sampling_level

3. filters file

Arguments of method

Note

SimpleGaReports.filtered_results method

SimpleGaReports.configure method

How to get private_key and client_email

1. Access to Google Cloud Platform Console

2. Create new project

3. Create service account for Google Analytics API and select API and Service from menu

4. Create authentication information

5. Select Service Account and download JSON Key

6. Open JSON Key file by editor and pick up "private_key" and "client_email"

7. They are the very Key-Value sets you want

8. They are the very Key-Value sets you want

9. Activate Analytics API

10. Add API user to Google Analytics

Sample App

Note

Prepare files

1. ./my_sample_app.rb

2. ./foo/my_key_and_email.yml

3. ./bar/my_ga_reporting_config.yml

4. ./foobar/filters.rb

execute script

Rails

Very Awesome Reference Book (Recommended)

Official documents

Core Reporting API - Reference Guide

Dimensions & Metrics Explorer

Query Explorer

API Rate Limits

TODO

Development

Contributing

License

Code of Conduct

2. Set `private_key` and `client_email`

`SimpleGaReports.filtered_results` method

`SimpleGaReports.configure` method

How to get `private_key` and `client_email`

3. Create service account for Google Analytics API and select `API and Service` from menu

6. Open JSON Key file by editor and pick up `"private_key"` and `"client_email"`

1. `./my_sample_app.rb`

2. `./foo/my_key_and_email.yml`

3. `./bar/my_ga_reporting_config.yml`

4. `./foobar/filters.rb`