ga_events 2.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 205433864fd2efabf0cf787da0be314c9bc48fd644773d8df29f6ca66327ba43
-  data.tar.gz: fa05cd8ee83f4b73fa23a3562e19d0ec2fcbb1a684c7ee49c357d0e78a54c3a7
+  metadata.gz: af13dc202f2b24f7fa7ba45345d90fea5158e4b50c5e55fbb6bbc68752c6083b
+  data.tar.gz: bbd3f2173bba05a2ce2d1dc4315a288b83b469810327dd2cbccd30799f6e595a
 SHA512:
-  metadata.gz: 472515474d12c53c4f3d43b8c577a45776ed983149c8347940294ca1128e907d101f48054eee7c00468cafdc3f1e7aba33c3cdfa08f43d81ebc0bd25c91f884f
-  data.tar.gz: 483bbdb595f20e852ec8f6b74366251e91e84b76cde7454721136d42cfd31586e36c88bd015ac6cbf321a673e2779e5f29b96cb345924d7606f648e36da67aa9
+  metadata.gz: cb529a2794580ae3c52a2a226c620b94ba79b278dc1171fcda5a27bdc511901b95f2d9243028285484a2a8d66af2feeb6a40539e82e5def320ed0974bf62e74e
+  data.tar.gz: 9b9adf95d667f066198b222cb45e233b83b03420e84a6743cd93cfba70b90bbaed7982b070d552f37e69c148a21800159a18223af176d6dac955049fe8f02971

data/.gitignore

@@ -1,5 +1,8 @@
 *.gem
+bin/rspec
 .bundle
 Gemfile.lock
 pkg
 vendor
+.ruby-version
+.tools-version

data/CHANGELOG.md

@@ -40,7 +40,7 @@ The format suggested at http://keepachangelog.com/ is used.
 - Ensure category, action and label do not include any umlauts or ß chars
 - Fixed an error where events are remaining after a redirect
 
-## 2.0.0 - 2018-04-03
+## 2.0.0 - 2020-11-20
 
 ### Removed
 - Support for rubies < 2.3
@@ -48,3 +48,45 @@ The format suggested at http://keepachangelog.com/ is used.
 
 ### Added
 - Compatibility for Rails 5
+
+## 2.1.0 - 2021-09-07
+
+### Added
+- Optional user consent flag to prevent event flushing until consent was given
+
+## 3.0.0 - 2022-01-10
+
+### Added
+- Universal Analytics Adapter can be configured to use `gtag.js` instead of
+  `analytics.js` event syntax
+  - [Breaking] The constructor interface has changed due to more configuration
+    options that differ between `analytics.js` and `gtag.js`.
+- Universal Analytics Adapter can be configured to use a custom name for the
+  analytics object (defaults to `window.ga()` for `analytics.js` and
+  `window.gtag()` for `gtag.js`)
+
+## 4.0.0 - 2023-08-xx
+
+### Added
+  - Support for GA4 using the `GTagAdapter`
+
+### Breaking
+-  Dropped support for older rubies. The gem requires at least ruby 3.2 now
+-  UniversalAnalyticsAdapter and GoogleAnalyticsAdapter removed
+-  The `GaEvent::Event` constructor changed to conform to the new newer
+GA4 event interface.
+
+  ```ruby
+  # 3.x and before
+  GaEvents::Event.new('category', 'action', 'label', 'value')
+
+  # 4.x onwards
+  GaEvents::Event.new('event_name', {
+    custom_dimension: 'xxx',
+    custom_dimension2: 'yyy'
+  })
+  ```
+- Events that should be kept on redirects are no longer mixed into rails
+flashes. Redirect events are stored inside a custom rack session variable
+instead.
+

data/Gemfile

@@ -7,5 +7,5 @@ gemspec
 
 gem 'pry'
 gem 'rake'
-gem 'rspec', '~> 3.1.0'
+gem 'rspec', '~> 3.12.0'
 gem 'rubocop', '~> 0.79.0', require: false

data/README.md

@@ -7,13 +7,13 @@ app.
 A rack middleware is automatically inserted into the stack. It transports
 the event data to the client. Normal requests get a DIV injected, Ajax requests
 get a data-pounded custom HTTP header appended. In case of redirects the data
-survives inside Rails' flash.
+survives inside of rack a rack session.
 The asset pipeline-ready CoffeeScript extracts this data on the client-side and
-pushes it to Google Analytics via ga.js or Google Tag Manager.
+pushes it to Google Analytics via gtag.js or Google Tag Manager.
 
 ## Dependencies
 
-* Ruby >= 2.3
+* Ruby >= 3.2
 * Rails 4.2 onwards
 * jQuery
 
@@ -35,27 +35,35 @@ Add to the top of your `application.js` (but after requiring jQuery):
 
 After requiring `ga_events.js`, you have to choose an adapter.
 
-### Google Analytics (ga.js)
+### Google Analytics 4 (gtag.js)
 
 ```javascript
 GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleAnalyticsAdapter();
+  return new GaEvents.GTagAdapter();
 }
 ```
 
-### Google Universal Analytics (analytics.js)
+Optionally you can specify a custom tracker GA_MEASUREMENT_ID where you want
+your events to be sent to:
 
 ```javascript
 GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter();
+  return new GaEvents.GTagAdapter(
+    {tracker_name: "GA_MEASUREMENT_ID"}
+  );
 }
 ```
 
-Optionally you can specify a custom method to call and a custom tracker name:
+#### Optional custom object name
+
+The default names of the analytics object for `gtag.js` is  `window.gtag()`. If
+you have renamed your analytics object, you can specify the name:
 
 ```javascript
 GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter("sendNow", "customTracker");
+  return new GaEvents.GTagAdapter(
+    {analytics_object_name: "analytics"} // calls window.analytics()
+  );
 }
 ```
 
@@ -98,24 +106,18 @@ HTTP header is added to the response.
 You can create a new event like this:
 
 ```ruby
-GaEvents::Event.new(category, action, label, value)
+GaEvents::Event.new('example_event', { extra: 'dimension' })
 ```
 
 On the client-side there is a similar interface to GaEvents:
 
 ```javascript
-new GaEvents.Event(category, action, label, value)
+new GaEvents.Event('example_event', { extra: 'dimension' })
 ```
 
 We have taken special care of tracking events while the DOM is loading.
 Events get collected until the DOM is ready and flushed afterwards.
 
-### Default values
-
-While collecting hundreds of thousands of events on a daily basis in
-Google Analytics we found corrupted aggregated events when the event label or
-value is omitted. We now enforce a default label ("-") and value (1).
-
 ### Too many events
 
 Use something like this snippet to get informed of bloating HTTP headers with
@@ -161,5 +163,6 @@ Yes please! Use pull requests.
 ## More docs and tools
 
 * [Google Analytics: Event Tracking](https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide)
+* [Google Universal Analytics: Event Tracking (gtag.js)](https://developers.google.com/analytics/devguides/collection/gtagjs/events)
 * [Google Tag Manager: Custom Events](http://support.google.com/tagmanager/answer/2574372#GoogleAnalytics)
-* [Chrome Web Store: Event Tracking Tracker](https://chrome.google.com/webstore/detail/event-tracking-tracker/npjkfahkbgoagkfpkidpjdemjjmmbcim)
+* [Chrome Web Store: Tag Assistant](https://chrome.google.com/webstore/detail/tag-assistant-legacy-by-g/kejbdjndbnbjgmefkgdddjlbokphdefk)

data/Rakefile

@@ -1,3 +1,8 @@
 # frozen_string_literal: true
 
 require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task default: :spec

data/app/assets/javascripts/ga_events.js.coffee

@@ -7,23 +7,27 @@ class GaEvents.Event
   adapter: null
   @list: []
   @may_flush: false
-  @header_key: "X-GA-Events"
+  @header_key: "x-ga-events"
   @html_key: "ga-events"
   @require_user_consent: false
   @user_consent_given: false
   klass: @
 
-  # Decompose a event-string (ruby side) into an event object.
-  @from_string: (string) ->
-    $.map string.split("$"), (part) =>
-      [category, action, label, value] = part.split "|"
-      new @(category, action, label, value)
+  # Decompose an event-string (ruby side) into an event object.
+  @from_json: (string) ->
+    events = JSON.parse(string)
+
+    $.map events, (event) =>
+      if event_name = event.__event__
+        delete event.__event__
+        new @(event_name, event)
 
   @from_dom: ->
-    dom_events = $("div[data-#{@html_key}]").data @html_key
-    @from_string dom_events if dom_events?
+    data_attribute = "data-#{@html_key}"
+    dom_events = $("div[#{data_attribute}]").attr data_attribute
+    @from_json dom_events if dom_events?
 
-  # Events should not be send to an adapter unless the DOM has finished loading.
+  # Events should not be sent to an adapter unless the DOM has finished loading.
   @flush: ->
     return if @require_user_consent && !@user_consent_given
 
@@ -32,33 +36,18 @@ class GaEvents.Event
       @list = []
 
   # Add all events to a queue to flush them later
-  constructor: (@category = "-", @action = "-", @label = "-", @value = 1) ->
+  constructor: (@event_name, @options = {}) ->
     @klass.list.push @
     @klass.flush()
 
-  escape: (str) ->
-    return unless str
-    "#{str}".replace(/ä/g, "ae")
-            .replace(/ö/g, "oe")
-            .replace(/ü/g, "ue")
-            .replace(/Ä/g, "Ae")
-            .replace(/Ö/g, "Oe")
-            .replace(/Ü/g, "Ue")
-            .replace(/ß/g, "ss")
-
-  to_hash: ->
-    # Category, action and label must be escaped and of type string.
-    action: @escape(@action)
-    category: @escape(@category)
-    label: @escape(@label)
-    # Value has to be a positive integer or defaults to 1
-    value: @to_positive_integer(@value)
-
-  to_positive_integer: (n) ->
-    if isFinite(n) and parseInt(n) >= 0 then parseInt n else 1
-
-  # https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide#SettingUpEventTracking
-  push_to_adapter: -> @klass.adapter().push @to_hash()
+  push_to_adapter: ->
+    if @is_valid_event_name()
+      @klass.adapter().push(@event_name, @options)
+    else
+      console.warn("GA4 event name \"#{@event_name}\" is invalid.") if console
+
+  # https://support.google.com/analytics/answer/13316687?hl=en#zippy=%2Cweb
+  is_valid_event_name: -> /^[a-z]+[a-z0-9_]*$/i.test(@event_name)
 
   jQuery =>
     @may_flush = true
@@ -66,7 +55,7 @@ class GaEvents.Event
 
     process_xhr = (xhr) =>
       xhr_events = xhr.getResponseHeader @header_key
-      @from_string xhr_events if xhr_events?
+      @from_json decodeURIComponent(xhr_events) if xhr_events?
 
     $(document).ajaxComplete((_, xhr) -> process_xhr(xhr))
     $(document).on "turbolinks:request-end", (event) ->
@@ -76,32 +65,31 @@ class GaEvents.Event
     @from_dom()
 
 
+class GaEvents.GTagAdapter
+  constructor: (options) ->
+    @analytics_object_name = options?.analytics_object_name || 'gtag'
+
+    # https://developers.google.com/analytics/devguides/migration/ua/analyticsjs-to-gtagjs#measure_pageviews_with_specified_trackers
+    @tracker_name = options?.tracker_name || false
+
+  push: (event_name, data) ->
+    data.send_to = @tracker_name if @tracker_name
+    window[@analytics_object_name]("event", event_name, data)
+
+class GaEvents.NullAdapter
+  push: (event_name, data) -> console.log(event_name, data) if console?
+
 class GaEvents.GoogleTagManagerAdapter
   constructor: (@event = "ga_event") ->
-  push: (data) ->
+
+  push: (event_name, data) ->
     data.event = @event
+    data.event_name = event_name
     data.non_interaction = true
     window.dataLayer.push data
 
-class GaEvents.GoogleUniversalAnalyticsAdapter
-  constructor: (@method_call_name = "send", tracker_name) ->
-    @method_call_name = "#{tracker_name}.#{@method_call_name}" if tracker_name
-
-  push: (h) ->
-    window.ga @method_call_name, "event", h.category, h.action, h.label,
-              h.value, {"nonInteraction": true}
-
-class GaEvents.GoogleAnalyticsAdapter
-  # Send events non_interactive => no influence on bounce rates
-  push: (h) ->
-    window._gaq.push(
-      ["_trackEvent", h.category, h.action, h.label, h.value, true]
-    )
-
-class GaEvents.NullAdapter
-  push: (obj) -> console.log obj if console?
-
 class GaEvents.TestAdapter
-  push: (obj) ->
+  push: (event_name, data) ->
+    loggedEvent = Object.assign({ event_name: event_name }, data)
     window.events = [] unless window.events?
-    window.events.push obj
+    window.events.push(loggedEvent)

data/ga_events.gemspec

@@ -25,6 +25,8 @@ Gem::Specification.new do |gem|
   gem.name          = 'ga_events'
   gem.require_paths = ['lib']
   gem.version       = GaEvents::VERSION
+  gem.licenses      = ['MIT']
 
+  gem.required_ruby_version = '>= 3.2'
   gem.add_dependency 'rails', '>= 4.2'
 end

data/lib/ga_events/event.rb

@@ -1,19 +1,37 @@
 # frozen_string_literal: true
 
 module GaEvents
-  Event = Struct.new(:category, :action, :label, :value) do
+  class Event
+    attr_reader :event_name, :event_params
+
     # Default values are set here, see README.md for details.
-    def initialize(category = '-', action = '-', label = '-', value = 1)
-      super
+    def initialize(event_name, event_params = {})
+      @event_name = event_name
+      @event_params = event_params
       GaEvents::List << self
     end
 
     def to_s
-      [category, action, label, value].join('|')
+      JSON.generate({ __event__: event_name, **event_params })
+    end
+
+    def to_h
+      { event_name:, event_params: event_params.symbolize_keys }
+    end
+
+    def deconstruct_keys(keys)
+      keys ? to_h.slice(*keys) : to_h
+    end
+
+    def self.from_hash(event_hash)
+      if event_name = event_hash.delete('__event__')
+        new(event_name, event_hash)
+      end
     end
 
-    def self.from_string(str)
-      new(*str.split('|'))
+    def ==(other)
+      self.class == other.class && event_name == other.event_name &&
+        event_params == other.event_params
     end
   end
 end

data/lib/ga_events/list.rb

@@ -12,13 +12,18 @@ module GaEvents
       def_delegators :data, :<<, :present?
 
       def to_s
-        data.collect(&:to_s).join('$')
+        "[#{data.collect(&:to_s).join(',')}]"
       end
 
       # Init list, optionally with a string of serialized events
       def init(str = nil)
         Thread.current[:ga_events] = []
-        (str || '').split('$').each { |s| GaEvents::Event.from_string(s) }
+        if str.present?
+          raw_events = JSON.parse(str)
+          raw_events.each { |raw_event| GaEvents::Event.from_hash(raw_event) }
+        end
+      rescue JSON::ParserError
+        nil
       end
 
       private

data/lib/ga_events/middleware.rb

@@ -4,6 +4,8 @@ require 'rack/utils'
 
 module GaEvents
   class Middleware
+    SESSION_GA_EVENTS_KEY = 'ga_events.events'
+
     def initialize(app)
       @app = app
     end
@@ -20,12 +22,11 @@ module GaEvents
         serialized = GaEvents::List.to_s
         if xhr_or_turbolinks?(request)
           # AJAX request
-          headers['X-GA-Events'] = serialized
-
+          headers['x-ga-events'] = CGI.escapeURIComponent(serialized)
         elsif redirect?(status)
-          # 30x/redirect? Then add event list to flash to survive the redirect.
-          add_events_to_flash(env, serialized)
-
+          # 30x/redirect? Then add event list to rack session to survive the
+          # redirect.
+          add_events_to_session(env, serialized)
         elsif html?(status, headers)
           response = inject_div(response, serialized)
         end
@@ -37,23 +38,14 @@ module GaEvents
     private
 
     def init_event_list(env)
-      flash = env['rack.session'] && env['rack.session']['flash'] &&
-              env['rack.session']['flash']['flashes']
-
-      # The key has to be removed from the flash here to ensure it does not
-      # remain after the finished redirect. This copies the behaviour of the
-      # "#use" and "#sweep" methods of the rails flash middleware:
-      # https://github.com/rails/rails/blob/v3.2.14/actionpack/lib/action_dispatch/middleware/flash.rb#L220
-      GaEvents::List.init(flash&.delete('ga_events'))
+      events = env['rack.session']&.delete(SESSION_GA_EVENTS_KEY)
+      GaEvents::List.init(events)
     end
 
-    def add_events_to_flash env, serialized_data
-      flash = env['rack.session'] && env['rack.session']['flash'] &&
-              env['rack.session']['flash']['flashes']
-
-      return unless flash
-
-      flash['ga_events'] = serialized_data
+    def add_events_to_session env, serialized_data
+      if session = env.dig('rack.session')
+        session[SESSION_GA_EVENTS_KEY] = serialized_data
+      end
     end
 
     def normalize_response(response)

data/lib/ga_events/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GaEvents
-  VERSION = '2.1.0'
+  VERSION = '4.0.0'
 end

data/spec/event_spec.rb

@@ -0,0 +1,68 @@
+require 'spec_helper'
+
+RSpec.describe GaEvents::Event do
+  it 'has a custom #to_s implementation ' do
+    expect(
+      described_class.new('test', { p1: 'my-action', p2: 'my-label' }).to_s
+    ).to eq('{"__event__":"test","p1":"my-action","p2":"my-label"}')
+  end
+
+  it 'can be restored from hash' do
+    initialized_event =
+      described_class.new(
+        'test',
+        {
+          'category' => 'my-category',
+          'label' => 'my-label',
+          'value' => 'my-value'
+        }
+      )
+    from_hash_event =
+      described_class.from_hash(
+        {
+          'category' => 'my-category',
+          '__event__' => 'test',
+          'label' => 'my-label',
+          'value' => 'my-value'
+        }
+      )
+    expect(from_hash_event).to eq initialized_event
+  end
+
+  it 'adds itself to GaEvents::List' do
+    described_class.from_hash(
+      {
+        '__event__' => 'test',
+        'category' => 'my-category',
+        'label' => 'my-label',
+        'value' => 'first-value'
+      }
+    )
+    described_class.new('clicked', { some: 'thing' })
+
+    expect(GaEvents::List.to_s).to eq(<<~EVENTS.tr("\n", ''))
+      [{"__event__":"test","category":"my-category","label":"my-label","value":"first-value"},
+      {"__event__":"clicked","some":"thing"}]
+    EVENTS
+  end
+
+  it 'can be initialized with a hash' do
+    expect(
+      described_class.new('one_value', { stars: 5 }).to_s
+    ).to eq '{"__event__":"one_value","stars":5}'
+    expect(
+      described_class.new('two_values', { stars: 5, mode: 'main' }).to_s
+    ).to eq '{"__event__":"two_values","stars":5,"mode":"main"}'
+    expect(
+      described_class.new('with_array', { list: [5, 'stars'] }).to_s
+    ).to eq '{"__event__":"with_array","list":[5,"stars"]}'
+  end
+
+  it 'can be pattern matched against' do
+    event = described_class.new('test', { stars: 5 })
+    event => {
+      event_name: 'test', event_params: { stars: Integer => five_stars }
+    }
+    expect(five_stars).to eq 5
+  end
+end

data/spec/list_spec.rb

@@ -0,0 +1,40 @@
+require 'spec_helper'
+
+RSpec.describe 'GaEvents::List' do
+  describe '#to_s' do
+    it 'generates valid json' do
+      GaEvents::Event.new('clicked', { a: 'a' })
+      GaEvents::Event.new('clicked', { b: 'b' })
+      expect(JSON.parse(GaEvents::List.to_s)).to eq(
+        [
+          { '__event__' => 'clicked', 'a' => 'a' },
+          { '__event__' => 'clicked', 'b' => 'b' }
+        ]
+      )
+    end
+  end
+
+  it 'can be initialized with a json string' do
+    GaEvents::List.init(<<~JSON.squish)
+      [
+        { "__event__": "clicked", "a": "a" }
+      ]
+    JSON
+
+    expect(
+      GaEvents::List.send(:data).to_h { [_1.event_name, _1.event_params] }
+    ).to eq({ 'clicked' => { 'a' => 'a' } })
+  end
+
+  it 'can be initialized with a broken json string' do
+    GaEvents::List.init(<<~JSON.squish)
+      [
+        { "__event__": "clicked", "trailing": "comma triggers ParserError", }
+      ]
+    JSON
+
+    expect(
+      GaEvents::List.send(:data).to_h { [_1.event_name, _1.event_params] }
+    ).to be_empty
+  end
+end

data/spec/middleware_spec.rb

@@ -33,26 +33,26 @@ describe GaEvents::Middleware do
     context 'events present in GaEvents::List' do
       let(:app) do
         proc do |_|
-          GaEvents::Event.new('category', 'action', 'label', 'value')
+          GaEvents::Event.new('test', { 'cool' => 'stuff' })
           [200, { 'Content-Type' => 'text/html' }, response_body]
         end
       end
 
-      context 'there is no body closing tag' do
+      context 'when no body closing tag exists' do
         let(:response) { request.get('/') }
         it 'leaves everything as it was' do
           expect(response.body).to eq response_body
         end
       end
 
-      context 'there exists body closing tag' do
+      context 'when a body closing tag exists' do
         let(:response) { request.get('/') }
         let(:response_body) { 'something awesome!</body>' }
 
         it 'injects data-ga-events' do
           expect(response.body).to eq(
             'something awesome!' \
-            "<div data-ga-events='category|action|label|value'></div></body>"
+            "<div data-ga-events='[{\"__event__\":\"test\",\"cool\":\"stuff\"}]'></div></body>"
           )
         end
       end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ga_events
 version: !ruby/object:Gem::Version
-  version: 2.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Florian Dütsch
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-09-07 00:00:00.000000000 Z
+date: 2023-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,10 +49,13 @@ files:
 - lib/ga_events/list.rb
 - lib/ga_events/middleware.rb
 - lib/ga_events/version.rb
+- spec/event_spec.rb
+- spec/list_spec.rb
 - spec/middleware_spec.rb
 - spec/spec_helper.rb
 homepage: https://github.com/Nix-wie-weg/ga_events
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message:
 rdoc_options: []
@@ -62,14 +65,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.4.6
 signing_key:
 specification_version: 4
 summary: This gem allows you to annotate events everywhere in the code of your Rails
@@ -79,5 +82,7 @@ summary: This gem allows you to annotate events everywhere in the code of your R
   extracts this data on the client side and pushes it to Google Analytics via ga.js
   or Google Tag Manager.
 test_files:
+- spec/event_spec.rb
+- spec/list_spec.rb
 - spec/middleware_spec.rb
 - spec/spec_helper.rb