{"id":21496561,"url":"https://github.com/mlibrary/irus_analytics","last_synced_at":"2025-07-31T09:11:34.529Z","repository":{"id":49181267,"uuid":"349532791","full_name":"mlibrary/irus_analytics","owner":"mlibrary","description":"Irus Analytics","archived":false,"fork":false,"pushed_at":"2023-09-14T19:04:09.000Z","size":93,"stargazers_count":1,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-23T15:23:42.912Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mlibrary.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-19T19:22:14.000Z","updated_at":"2024-08-21T15:21:15.000Z","dependencies_parsed_at":"2025-04-23T15:23:01.379Z","dependency_job_id":"8310e9e3-f2fc-4762-850d-4cbc103b0d19","html_url":"https://github.com/mlibrary/irus_analytics","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/mlibrary/irus_analytics","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Firus_analytics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Firus_analytics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Firus_analytics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Firus_analytics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mlibrary","download_url":"https://codeload.github.com/mlibrary/irus_analytics/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mlibrary%2Firus_analytics/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268017017,"owners_count":24181657,"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","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-11-23T16:17:12.399Z","updated_at":"2025-07-31T09:11:34.464Z","avatar_url":"https://github.com/mlibrary.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# IrusAnalytics\n\nIrusAnalytics is a gem that provides a simple way to send analytics to the IRUS repository aggregation service.  \n\nMore information about IRUS can be found at [https://irus.jisc.ac.uk/r5/](https://irus.jisc.ac.uk/r5/). In summary the IRUS service is designed to provide item-level usage statistics, both for Investigations (views) and Requests (downloads), for Institutional Repositories.  To sign up and use IRUS, please see the above link. \n\nThis gem was developed for use with a Hyrax repository [http://samvera.org/](http://samvera.org/), but it can be used with any other web application supporting Ruby gems. \n\nMore information on COUNTER reports and reporting can be found at [Project COUNTER](https://www.projectcounter.org/)\n\n## Build Status\n![Build Status](https://api.travis-ci.org/uohull/irus_analytics.png?branch=master)\n## Prerequisite\n\n[Blacklight OAI Provider](https://github.com/projectblacklight/blacklight_oai_provider) or some other method of displaying an OAI feed of your works or digital objects. While the irus_analytics gem will push limited usage data to IRUS, they still need a way to harvest your repository metadata (like Title, Author, etc) to create COUNTER usage reports.\n\n## Installation\n\nAdd this line to your rails application Gemfile:\n\n    gem 'irus_analytics', git: 'https://github.com/mlibrary/irus_analytics'\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install irus_analytics\n\n## Usage\n\nOnce you have the gem, run the following generator:\n\n    $ bundle exec rails generate irus_analytics:config\n\nOr:\n\n    $ rails g irus_analytics:config\n\nThis will generate editable configuration and translation files in the config folder.\n\n### config/irus_analytics_config.yml\n\nThis uses a similar mechanism to the standard rails database.yml file to allow for per-environment configuration of the values for:\n\n**source_repository**\\\n is used to configure the name of the source respository url (i.e. what the url for your repository)\n\n**irus_server_address**\\\n is used to define the IRUS server endpoint, this can be configured for the test version of the service.\n\n**robots_file**\\\nis used to specify the name of the file containing the robot UserAgents as regular expressions.  \n\n**Example installed file**\n\n\u003cpre\u003e\ndevelopment:\n  enabled: true\n  enable_send_logger: true\n  irus_server_address: https://irus.jisc.ac.uk/counter/test/\n  robots_file: irus_analytics_counter_robot_list.txt\n  source_repository: localhost\n  verbose_debug: true\ntest:\n  enabled: true\n  enable_send_logger: false\n  irus_server_address: https://irus.jisc.ac.uk/counter/test/\n  robots_file: irus_analytics_counter_robot_list.txt\n  source_repository: production\n  verbose_debug: false\nproduction:\n  enabled: true\n  enable_send_logger: false\n  irus_server_address: https://irus.jisc.ac.uk/counter/test/\n  robots_file: irus_analytics_counter_robot_list.txt\n  source_repository: production\n  verbose_debug: false\n\u003c/pre\u003e\n\n**Add named server section**\n\n\u003cpre\u003e\nproduction:\n  enabled: true\n  enable_send_investigations: true\n  enable_send_logger: true\n  enable_send_requests: true\n  irus_server_address: https://irus.jisc.ac.uk/counter/test/\n  robots_file: irus_analytics_counter_robot_list.txt\n  source_repository: deepblue.lib.umich.edu/data\n  verbose_debug: true\n  named_servers: true\n  deepblue.local:\n    source_repository: localhost.deepblue.lib.umich.edu/data\n  staging.deepblue.lib.umich.edu:\n    source_repository: testing.deepblue.lib.umich.edu/data\n  testing.deepblue.lib.umich.edu:\n    source_repository: testing.deepblue.lib.umich.edu/data\n\u003c/pre\u003e\n\n\n### Integration\nThe IrusAnalytics code is designed to be called after an Investigation (view) or Request (download) event has happened in your application. The following code added to the Rails controller handles the content download.\n\nTo add request handling to a controller, run the following:\n\nNote: options are sent as single string, space separated options, option_name:value\n\n`type:investigation` or `type:request`\n\n`after_action:show`\n\n`controller_class_name:Hyrax::DissertationsController`\n\n**Inject Request controller hooks (test mode)**\n\u003cpre\u003e\nbundle exec rails generate irus_analytics:inject_controller_hooks \"type:request after_action:zip_download controller_class_name:Hyrax::DissertationsController test_mode:true\"\n\u003c/pre\u003e\n\n**Inject Investigation controller hooks (test mode)**\n\u003cpre\u003e\nbundle exec rails generate irus_analytics:inject_controller_hooks \"type:investigation after_action:show controller_class_name:Hyrax::DissertationsController test_mode:true\"\n\u003c/pre\u003e\n\n\n**Inject Request controller hooks**\n\u003cpre\u003e\nbundle exec rails generate irus_analytics:inject_controller_hooks \"type:request after_action:zip_download controller_class_name:Hyrax::DissertationsController\"\n\u003c/pre\u003e\n\n**Inject Investigation controller hooks**\n\u003cpre\u003e\nbundle exec rails generate irus_analytics:inject_controller_hooks \"type:investigation after_action:show controller_class_name:Hyrax::DissertationsController\"\n\u003c/pre\u003e\n\nA simple example of before and after of running both Investigation and Request generators against `Hyrax::DissertationsController`:\n\n**Before**\n\n\u003cpre\u003e\n# frozen_string_literal: true\n\nmodule Hyrax\n  # Generated controller for Dissertation\n  class DissertationsController \u003c DeepblueController\n    # Adds Hyrax behaviors to the controller.\n    include Hyrax::WorksControllerBehavior\n    #include Hyrax::BreadcrumbsForWorks\n    self.curation_concern_type = ::Dissertation\n\n    # Use this line if you want to use a custom presenter\n    self.show_presenter = Hyrax::DissertationPresenter\n  end\nend\n\u003c/pre\u003e\n\n**After**\n\n\u003cpre\u003e\n# frozen_string_literal: true\n\nmodule Hyrax\n  # Generated controller for Dissertation\n  class DissertationsController \u003c DeepblueController\n    # Adds Hyrax behaviors to the controller.\n    include Hyrax::WorksControllerBehavior\n    # begin inject IrusAnalytics::InjectControllerHooksGenerator: include IrusAnalytics controller behavior\n    include IrusAnalytics::Controller::AnalyticsBehaviour\n    # end inject IrusAnalytics::InjectControllerHooksGenerator: include IrusAnalytics controller behavior\n    # begin inject IrusAnalytics::InjectControllerHooksGenerator: IrusAnalytics after action\n    after_action :send_irus_analytics_request, only: [:zip_download]\n    # end inject IrusAnalytics::InjectControllerHooksGenerator: IrusAnalytics after action\n    # begin inject IrusAnalytics::InjectControllerHooksGenerator: IrusAnalytics after action\n    after_action :send_irus_analytics_investigation, only: [:show]\n    # end inject IrusAnalytics::InjectControllerHooksGenerator: IrusAnalytics after action\n\n  public\n    # begin inject IrusAnalytics::InjectControllerHooksGenerator: item_identifier_for_irus_analytics\n    def item_identifier_for_irus_analytics\n      # return the OAI identifier\n      # http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm\n      CatalogController.blacklight_config.oai[:provider][:record_prefix] + \":\" + params[:id]\n    end\n    # end inject IrusAnalytics::InjectControllerHooksGenerator: item_identifier_for_irus_analytics\n    # begin inject IrusAnalytics::InjectControllerHooksGenerator: skip_send_irus_analytics?\n    def skip_send_irus_analytics?(usage_event_type)\n      # return true to skip tracking, for example to skip curation_concerns.visibility == 'private'\n      case usage_event_type\n      when 'Investigation'\n        false\n      when 'Request'\n        false\n      end\n    end\n    # end inject IrusAnalytics::InjectControllerHooksGenerator: skip_send_irus_analytics?\n\n\n    #include Hyrax::BreadcrumbsForWorks\n    self.curation_concern_type = ::Dissertation\n\n    # Use this line if you want to use a custom presenter\n    self.show_presenter = Hyrax::DissertationPresenter\n  end\nend\n\u003c/pre\u003e\n\n\n## In Summary (to do)\n\nTherefore in summary...\n\n    include IrusAnalytics::Controller::AnalyticsBehaviour  \n  \n    after_filter :send_analytics, only: [:show]\n\n    def item_identifier_for_irus_analytics\n      CatalogController.blacklight_config.oai[:provider][:record_prefix] + \":\" + params[:id]\n    end\n\n... needs adding to the relevant controller.\n\nNOTE: If you are not using the [Blacklight OAI Provider](https://github.com/projectblacklight/blacklight_oai_provider) gem to create your OAI feed, you'll need to modify the `item_identifier_for_irus_analytics` method to conform with your application's [OAI identifiers](http://www.openarchives.org/OAI/2.0/guidelines-oai-identifier.htm).\n\nTo be compliant with the IRUS client requirements/recommendations this Gem makes use of the Resque  [https://github.com/resque/resque](https://github.com/resque/resque).  Resque provides a simple way to create background jobs within your Ruby application, and is specifically used within this gem to push the analytics posts onto a queue.  This means the download functionality within your application is unaffected by the send analytics call, and it provides a means of queuing analytics if the IRUS server is down. \n\nNote: Resque requires Redis to be installed  \n\nBy installing this gem, your application should have access to the Resque rake tasks.  These can be seen by running \"rake -T\",  the list should include:-\n\n    rake resque:failures:sort \n    rake resque:work\n    rake resque:workers\n\nTo start the resque background job for this gem use\n\n    QUEUE=irus_analytics rake environment resque:work\n\n## Additional Notes for Hyrax\n\nIn a Hyrax application, the `Hyrax::DownloadsController` and `Hyrax::FileSetsController` will be in the Hyrax gem itself so the irus_analytics generator will not write to them. One can copy the entirety of these classes (and relevent specs) into one's application or can use the Module#Prepend pattern to add/modify the neccessary methods. An example for how to do this in Hyrax for a Presenter (but the idea is the same for Controllers) is here, https://samvera.github.io/patterns-presenters.html#overriding-and-custom-presenter-methods, or try something like:\n\n```\n# app/controllers/concerns/download_override.rb (or whatever convention you use)\n\nHyrax::DownloadsController.class_eval do\n  prepend(DownloadsControllerBehavior = Module.new do\n    include IrusAnalytics::Controller::AnalyticsBehaviour\n\n    # Render the 404 page if the file doesn't exist.\n    # Otherwise renders the file.\n    def show\n      case file\n      when ActiveFedora::File\n        # For original files that are stored in fedora\n        send_irus_analytics_request\n        super\n      when String\n        # For derivatives stored on the local file system\n        send_local_content\n      else\n        raise Hyrax::ObjectNotFoundError\n      end\n    end\n\n    def item_identifier_for_irus_analytics\n      # return the OAI identifier\n      CatalogController.blacklight_config.oai[:provider][:record_prefix] + \":\" + FileSet.find(params[:id]).parent.id\n    end\n  end\nend\n```\n\nwhere we add the `item_identifier_for_irus_analytics` method which reports the parent's or work's OAI identifier and we explicitly call the `send_irus_analytics_request` method only for Fedora downloads, not for derivatives like thumbnails since those are explicitly not considered Requests per COUNTER.\n\nAnd then in application.rb something like:\n\n```\nconfig.to_prepare do\n  # ensure overrides are loaded\n  # see https://bibwild.wordpress.com/2016/12/27/a-class_eval-monkey-patching-pattern-with-prepend/\n  Rails.configuration.cache_classes ? require(\"app/controllers/concerns/download_override.rb\") : load(\"app/controllers/concerns/download_override.rb\")\nend\n```\n\n## Contributing\n\n1. Fork it ( https://github.com/uohull/irus_analytics/fork )\n2. Create your feature branch (`git checkout -b my-new-feature`)\n3. Commit your changes (`git commit -am 'Add some feature'`)\n4. Push to the branch (`git push origin my-new-feature`)\n5. Create a new Pull Request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Firus_analytics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmlibrary%2Firus_analytics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmlibrary%2Firus_analytics/lists"}