{"id":24571012,"url":"https://github.com/nikukyugamer/simple-ga-reporting","last_synced_at":"2025-03-17T08:26:12.505Z","repository":{"id":48456024,"uuid":"128010489","full_name":"nikukyugamer/simple-ga-reporting","owner":"nikukyugamer","description":"With simple configuration (by YAML), you can obtain Google Analytics reporting data","archived":false,"fork":false,"pushed_at":"2022-03-07T17:49:41.000Z","size":742,"stargazers_count":0,"open_issues_count":5,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T01:45:18.745Z","etag":null,"topics":["gem","gems","google-analytics","ruby"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/simple_ga_reporting","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nikukyugamer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-04T05:15:06.000Z","updated_at":"2021-07-05T22:14:29.000Z","dependencies_parsed_at":"2022-09-18T11:40:27.074Z","dependency_job_id":null,"html_url":"https://github.com/nikukyugamer/simple-ga-reporting","commit_stats":null,"previous_names":["corselia/simple-ga-reporting"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikukyugamer%2Fsimple-ga-reporting","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikukyugamer%2Fsimple-ga-reporting/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikukyugamer%2Fsimple-ga-reporting/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nikukyugamer%2Fsimple-ga-reporting/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nikukyugamer","download_url":"https://codeload.github.com/nikukyugamer/simple-ga-reporting/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243997731,"owners_count":20381084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gem","gems","google-analytics","ruby"],"created_at":"2025-01-23T17:58:57.087Z","updated_at":"2025-03-17T08:26:12.483Z","avatar_url":"https://github.com/nikukyugamer.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Gem Version](https://badge.fury.io/rb/simple_ga_reporting.svg)](https://badge.fury.io/rb/simple_ga_reporting) [![CircleCI](https://circleci.com/gh/nikukyugamer/simple-ga-reporting.svg?style=svg)](https://circleci.com/gh/nikukyugamer/simple-ga-reporting)\n\n# Japanese Document\n- Japanese Document (my blog's article) is following\n    - [Google Analytics の API を用いて簡単にデータを取得できる gem を作りました](https://obel.hatenablog.jp/entry/20180409/1523282148)\n\n# What's this?\nThis gem helps you to obtain `Google Analytics` reporting data with ease.\n\nFirst of all, you create configuration YAML file as Google Analytics API. Then execute the simple Ruby code, and you obtain Google Analytics reporting data.\n\nYeah, very simple :)\n\n## Wrapper gem of Legato\nThis gem is a wrapper of [Legato gem](https://github.com/tpitale/legato). `Legato` is very coooooooool and full-stack gem, so complicated as a beginner (me!).\n\nTherefore I developed this wrapper gem, `simple_ga_reporting`.\n\n# Get Started\n\n## 1. Installation\n```bash\n$ gem install simple_ga_reporting\n```\n\n## 2. Set `private_key` and `client_email`\n- There are two ways to set `private_key` and `client_email`\n- How to get above two Key-Value sets is written later\n\n### 2-1. The first way: Create API configuration file\n- Create `./config/key_and_email.yml`\n- This YAML file must contain two Key-Value sets\n    - `private_key` and its value\n    - `client_email` and its value\n\n### 2-2. The second way: Set values as arguments\n- Set arguments of `SimpleGaReports.filtered_results` method\n- For example:\n    - `SimpleGaReports.filtered_results(private_key: 'FOO', client_email: 'BAR')`\n- Convenient when you set by environment variables\n\n## 3. Create Google Analytics reporting configuration file\n- You must create the YAML file which contains Google Analytics reporting configuration such as `start-date`, `end-date`, `metrics`, `demensions`, `filters` and etc.\n- filepath is `./config/ga_reporting_config.yml`\n- This YAML file format is shown later\n\n## 4. Create filters file (Optional)\n- If you wanna use filters function, please create `./config/filters.rb`\n- the filters configuration on GUI is below\n\n![filter configuration on GUI](images/config_filter_by_gui.png)\n\n## 5. Write your app\n- Write your application used this gem\n- The sample code is below\n    - Use only two class methods\n        - `SimpleGaReports.configure`\n        - `SimpleGaReports.filtered_results`\n    - Only three lines :-)\n    - Note\n        - If you don't use filters, use `SimpleGaReports.raw_results` too\n        - when no filter is in configure file, `SimpleGaReports.raw_results` is the same as `SimpleGaReports.filtered_results`\n\n```ruby\nrequire 'simple_ga_reporting'\n\nSimpleGaReports.configure\nSimpleGaReports.filtered_results #=\u003e Legato::Query\n```\n\n# Detail of configuration\n\n## 1. Configuration of API account\n- You must set Google Analytics API configuration, `private_key` and `client_email`\n- There are two ways to set it\n    - The one is by arguments\n        - Set arguments of `SimpleGaReports.filtered_results` method\n    - The other is by YAML file\n        - Default filepath is `./config/key_and_email.yml`\n        - You can change filepath by argument\n- The sample of YAML file is below\n\n```yaml\nprivate_key: \"-----BEGIN PRIVATE KEY-----\\nMIIE..........Eqw==\\n-----END PRIVATE KEY-----\\n\"\nclient_email: \"your_account_name@foobar.iam.gserviceaccount.com\"\n```\n\n## 2. Google Analytics reporting configuration\n- You must create the YAML file which contains Google Analytics reporting configuration\n- Default filepath is `./config/ga_reporting_config.yml`\n    - You can change filepath by argument in `SimpleGaReports.configure` method\n- The sample of YAML file is below\n\n```yaml\nprofile_name: my_profile_name\nstart_date: 2018-04-01\nend_date: 2018-04-05\nmetrics:\n  - users\n  - pageviews\ndimensions:\n  - pagePath\n  - pageTitle\nsort:\n  - -pageviews\n  - -users\nfilters:\n  - my_awesome_filter\n  - his_awesome_filter\n  - her_awesome_filter\nlimit: 20\n```\n\n- Please refer the official documents as Key-Value sets\n    - https://developers.google.com/analytics/devguides/reporting/core/v3/reference\n\n![ga_query_parametes_summary.png](images/ga_query_parametes_summary.png)\n\n- Though above official documents show many Key-Value sets, you can config only several sets as below\n    - start-date\n    - end-date\n    - metrics\n    - dimensions\n    - sort\n    - filters\n    - max-results\n    - samplingLevel\n- Some Key names in configure file are different from ones in official document\n    - `start_date` in configure file (not `start-date`)\n    - `end_date` in configure file (not `end-date`)\n    - `limit` in configure file (instead of `max-results`)\n    - `sampling_level` in configure file (not `samplingLevel`)\n- The type of `metrics`, `dimensions`, `sort` and `filters` is `Array`\n    - The order of elements doesn't matter\n\n### 2-1. Key-Value detail\n\n#### profile_name\n- REQUIRED\n- It was called `view (view name)` before\n    - but in Japanese page, still `ビュー名`\n\n![View or Profile](images/ga_profile(view).png)\n\n#### start_date\n- REQUIRED\n- Original Key name is `start-date`\n- Value examples\n    - `2018-04-01`\n    - `today` or `yesterday`\n    - `14daysAgo`\n        - use `daysAgo` phrase even if `1day`\n\n#### end_date\n- REQUIRED\n- Original Key name is `end-date`\n- Value examples are the same as `start-date`\n\n#### metrics\n- REQUIRED\n- `指標` in Japanese\n- Official documents are below (very useful!)\n    - [Dimensions \u0026 Metrics Explorer](https://developers.google.com/analytics/devguides/reporting/core/dimsmets)\n- Value examples\n    - `users`\n    - `uniquePageviews`\n\n![Dimensions \u0026 Metrics Explorer](images/dimensions_and_metrics_explorer.png)\n\n#### dimensions\n- optional\n- Official documents are below (very useful!)\n    - [Dimensions \u0026 Metrics Explorer](https://developers.google.com/analytics/devguides/reporting/core/dimsmets)\n- Value examples\n    - `pagePath`\n    - `sessionCount`\n\n#### sort\n- optional\n- prefix\n    - `-` sign means descending\n    - no sign means ascending\n        - Don't use `+` sign\n- Value examples\n  - `-pageviews`\n  - `users`\n\n#### filters\n- optional\n- Value is method name you named in `filters.rb`\n\n#### limit\n- optional\n- Original Key name is `max-results`\n- Value is max amount of returned rows\n- Default value is `100`\n\n#### sampling_level\n- optional\n- Original Key name is `samplingLevel`\n- Default value is `HIGHER_PRECISION`\n\n## 3. filters file\n- You use filters function using `filters.rb` file\n    - the filename `filters.rb` is determined\n        - only filepath is optional\n    - the module name `Filters` is determined\n    - Default filepath is `./config/filters.rb`\n        - You can change it by argument with `configure` method\n- Examples\n\n```ruby\nmodule Filters\n  def chrome_or_fx\n    filter :chrome_or_fx, \u0026lambda { contains(:browser, 'Chrome|Firefox') }\n  end\n\n  def awesome_page\n    filter :awesome_page, \u0026lambda { contains(:pagePath, '\\A.*awesome.*\\z') }\n  end\nend\n```\n\n- `chrome_or_fx` method filters the results\n    - pick up data which contains 'Google Chrome' or 'Firefox' as browser\n- the convention of filter method is below\n    - define method name\n    - define filter name by symbol which is the same as method name\n    - define filter behavior by block object\n- Usage of multiple filters\n    - If you want to apply AND-chain, only specify each filter in Google Analytics reporting configuration file\n    - If you want to apply OR-chain, use regexp in block object as `chrome_or_fx` method\n- Adding refer [Legato's Documents](https://github.com/tpitale/legato#google-analytics-supported-filtering-methods)\n\n# Arguments of method\n\n## Note\n**YOU MUST SPECIFY ARGUMENTS AS RELATIVE FILEPATH SO YOU MUST ADD './' (dot slash) AT BEGINNING**\n\n- Set arguments of `SimpleGaReports.filtered_results` method\n- For example:\n    - `SimpleGaReports.filtered_results(private_key: 'FOO', client_email: 'BAR')\n- Convenient when you set by environment variables\n\n## `SimpleGaReports.filtered_results` method\n- If you don't use filters, use `SimpleGaReports.raw_results` method instead of `SimpleGaReports.filtered_results` method\n    - when no filter is in configure file, `SimpleGaReports.raw_results` is the same as `SimpleGaReports.filtered_results`\n- take three arguments\n    - All arguments are keyword ones\n    - You must set (`key_and_email_file`) or (`private_key` and `client_email`)\n\n1. `key_and_email_file`\n    - default is `./config/key_and_email.yml`\n\n1. `private_key`\n    - default is `nil`\n\n1. `client_email`\n    - default is `nil`\n\n## `SimpleGaReports.configure` method\n- take three arguments\n    - All arguments are keyword ones\n\n1. `report_config`\n    - first argument\n    - YAML file\n    - default is `./config/ga_reporting_config.yml`\n\n2. `filters`\n    - second argument\n    - filter file\n    - default is `./config/filters.rb`\n\n3. `**options`\n    - third argument\n    - default is nil\n    - if you set this argument, you can overwrite values in Google Analytics reporting configuration file\n    - example\n        - `start_date: '90daysAgo', end_date: '60daysAgo', limit: 100`\n\n# How to get `private_key` and `client_email`\n\n#### 1. Access to [Google Cloud Platform Console](https://console.cloud.google.com/)\n\n#### 2. Create new project\n- name new project as you like\n\n#### 3. Create service account for Google Analytics API and select `API and Service` from menu\n\n![Google Cloud Platform API menu](images/gcp_api_menu.png)\n\n#### 4. Create authentication information\n- Select `Service Account Key`\n\n![Google Cloud Platform API Auth Info](images/gcp_api_auth_info.png)\n\n#### 5. Select Service Account and download JSON Key\n\n![Google Cloud Platform JSON Key](images/gcp_download_json_key.png)\n\n#### 6. Open JSON Key file by editor and pick up `\"private_key\"` and `\"client_email\"`\n\n![Google Cloud Platform private_key and client_email](images/gcp_private_key_and_client_email.png)\n\n#### 7. They are the very Key-Value sets you want\n- Deal with them carefully\n\n#### 8. They are the very Key-Value sets you want\n- Deal with them carefully\n\n#### 9. Activate Analytics API\n- NOT `Google Analytics Reporting API` BUT `Analytics API`\n\n![GCP Activate API 01](images/gcp_activate_api_01.png)\n\n![GCP Activate API 02](images/gcp_activate_api_02.png)\n\n![GCP Activate API 03](images/gcp_activate_api_03.png)\n\n#### 10. Add API user to Google Analytics\n- In Google Analytics, add mail address of API user\n- Only `Display and Analytics` authority needs\n\n![ga_add_api_user.png](images/ga_add_api_user.png)\n\n# Sample App\n\n## Note\n**YOU MUST SPECIFY ARGUMENTS AS RELATIVE FILEPATH SO YOU MUST ADD './' (dot slash) AT BEGINNING**\n\n## Prepare files\n\n1. `./my_sample_app.rb`\n1. `./foo/my_key_and_email.yml`\n1. `./bar/my_ga_reporting_config.yml`\n1. `./foobar/filters.rb`\n\n#### 1. `./my_sample_app.rb`\n```ruby\nrequire 'simple_ga_reporting'\n\nSimpleGaReports.configure(report_config: './bar/my_ga_reporting_config.yml', filters: './foobar/filters.rb', start_date: '2daysAgo', limit: 100)\nresults = SimpleGaReports.filtered_results(key_and_email: './foo/my_key_and_email.yml') # or use arguments of 'private_key:' and 'client_email:'\n\nresults.each do |result|\n  puts '==================================='\n  puts result['pagePath']\n  puts result['pageTitle']\n  puts result['pageviews']\n  puts result['users']\nend\n```\n\n#### 2. `./foo/my_key_and_email.yml`\n```yaml\nprivate_key: \"-----BEGIN PRIVATE KEY-----\\nMIIE..........Eqw==\\n-----END PRIVATE KEY-----\\n\"\nclient_email: \"your_account_name@foobar.iam.gserviceaccount.com\"\n```\n\n- You can set two key and value by not only YAML file but also arguments of `SimpleGaReports.filtered_results` method\n\n#### 3. `./bar/my_ga_reporting_config.yml`\n```yaml\nprofile_name: my_profile_name\nstart_date: 2018-04-01\nend_date: 2018-04-05\nmetrics:\n  - users\n  - pageviews\ndimensions:\n  - pagePath\n  - pageTitle\nsort:\n  - -pageviews\n  - -users\nfilters:\n  - chrome_or_fx\n  - happy_page\nlimit: 20\n```\n\n#### 4. `./foobar/filters.rb`\n```ruby\nmodule Filters\n  def chrome_or_fx\n    filter :chrome_or_fx, \u0026lambda { contains(:browser, 'Chrome|Firefox') }\n  end\n\n  def happy_page\n    filter :happy_page, \u0026lambda { contains(:pagePath, '\\A.*happy.*\\z') }\n  end\nend\n```\n\n## execute script\n```bash\n$ ruby ./my_sample_app.rb\n===================================\n/i_am_happy.html\nI am HAPPY!\n10000\n1000\n===================================\n/happy/index.html\nHAPPY TOP\n9000\n900\n===================================\n/path/to/happy.html\nAre You Happy?\n8000\n800\n===================================\n/happy.php\nHAPPY CHECK!\n7000\n700\n===================================\n......\n```\n\n# Rails\nWhen you use this gem on Rails, it's simple :)\n\n1. add this gem to `Gemfile`\n2. `$ bundle install`\n3. after it, the same way above\n\n# Very Awesome Reference Book (Recommended)\n- [わかばちゃんと学ぶ Googleアナリティクス (Let's study Google Analytics with Wakaba-Chan)](http://www.c-r.com/book/detail/1217)\n\n![わかばちゃんと学ぶ Googleアナリティクス](http://www.c-r.com/book/images/x/86354-232-7_x.jpg)\n\n- Created by [Ai Minatogawa](https://llminatoll.github.io/)\n    - She is an energetic creator!\n- Japanese version only\n    - English version will...?\n\n# Official documents\n## Core Reporting API - Reference Guide\n- https://developers.google.com/analytics/devguides/reporting/core/v3/reference\n\n## Dimensions \u0026 Metrics Explorer\n- https://developers.google.com/analytics/devguides/reporting/core/dimsmets\n\n## Query Explorer\n- https://ga-dev-tools.appspot.com/query-explorer/\n\n## API Rate Limits\n- https://developers.google.com/analytics/devguides/reporting/core/v3/limits-quotas\n\n# TODO\n- can input not only `profile_name` but also `profile id (view id)`\n- implement following query parametes\n    - offset\n    - quota_user\n    - segment_id\n        - ~~`segment` is the same as conbination of filters, so you can use 'filters' as alternative way~~\n        - `segment` is the first filter for initial population and it can't substitute\n\n# Development\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n# Contributing\nBug 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](http://contributor-covenant.org) code of conduct.\n\n# License\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n# Code of Conduct\nEveryone interacting in the SimpleGaReporting project’s codebases, issue trackers, chat rooms and mailing lists is\nexpected to follow the [code of conduct](https://github.com/corselia/simple-ga-reporting/blob/master/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikukyugamer%2Fsimple-ga-reporting","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnikukyugamer%2Fsimple-ga-reporting","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnikukyugamer%2Fsimple-ga-reporting/lists"}