ga_events 3.0.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2da2467a5f1cf24ef9fdcd30dfea8130a6e5a1c2a8ce6e0903143a909215e30d
-  data.tar.gz: b617a6d911b6666a8b1f0dabae680950565f956adccf26850a443a3109602c23
+  metadata.gz: af13dc202f2b24f7fa7ba45345d90fea5158e4b50c5e55fbb6bbc68752c6083b
+  data.tar.gz: bbd3f2173bba05a2ce2d1dc4315a288b83b469810327dd2cbccd30799f6e595a
 SHA512:
-  metadata.gz: 805237d9af985bd8c4cb9d696626f4949d953dcabb3669b1b80771209811f13402f27e25aa618eda39bce2cfdf767ae9f74fa8336f789e5a5ee79a82e59e8026
-  data.tar.gz: 428a307570718be7d541f3c8883cc73141e88e7861e87a98ed5a4263ef8f41f657028220203298ea4ab5053fdbe9e1e85dc9fec59e26b50223ba5a94a0855a0a
+  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

@@ -64,3 +64,29 @@ The format suggested at http://keepachangelog.com/ is used.
 - 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,42 +35,11 @@ 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();
-}
-```
-
-### Google Universal Analytics
-
-#### analytics.js
-
-```javascript
-GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter();
-}
-```
-
-Optionally you can specify a custom send method to call and a custom tracker
-name:
-
-```javascript
-GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter(
-    {send_method_name: "sendNow", tracker_name: "customTracker"}
-  );
-}
-```
-
-#### gtag.js
-
-```javascript
-GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter(
-    {use_gtag_variant: true}
-  );
+  return new GaEvents.GTagAdapter();
 }
 ```
 
@@ -79,21 +48,20 @@ your events to be sent to:
 
 ```javascript
 GaEvents.Event.adapter = function() {
-  return new GaEvents.GoogleUniversalAnalyticsAdapter(
-    {use_gtag_variant: true, tracker_name: "GA_MEASUREMENT_ID"}
+  return new GaEvents.GTagAdapter(
+    {tracker_name: "GA_MEASUREMENT_ID"}
   );
 }
 ```
 
 #### Optional custom object name
 
-The default names of the analytics object are `window.ga()` for `analytics.js`
-and `window.gtag()` for `gtag.js`. If you have renamed your analytics object,
-you can specify the 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(
+  return new GaEvents.GTagAdapter(
     {analytics_object_name: "analytics"} // calls window.analytics()
   );
 }
@@ -138,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
@@ -201,7 +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 (analytics.js)](https://developers.google.com/analytics/devguides/collection/analyticsjs/events)
 * [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: Tag Assistant](https://chrome.google.com/webstore/detail/tag-assistant-legacy-by-g/kejbdjndbnbjgmefkgdddjlbokphdefk)

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

@@ -7,21 +7,25 @@ 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 an 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)
+  @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 sent to an adapter unless the DOM has finished loading.
   @flush: ->
@@ -32,32 +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
-
-  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
@@ -65,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) ->
@@ -75,59 +65,31 @@ class GaEvents.Event
     @from_dom()
 
 
-class GaEvents.GoogleTagManagerAdapter
-  constructor: (@event = "ga_event") ->
-  push: (data) ->
-    data.event = @event
-    data.non_interaction = true
-    window.dataLayer.push data
-
-class GaEvents.GoogleUniversalAnalyticsAdapter
+class GaEvents.GTagAdapter
   constructor: (options) ->
-    @use_gtag_variant = options?.use_gtag_variant || false
-    @analytics_object_name =
-      options?.analytics_object_name ||
-      (if @use_gtag_variant then "gtag" else "ga")
-
-    # Only relevant for analytics.js
-    @send_method_name = options?.send_method_name || "send"
+    @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: (data) ->
-    if @use_gtag_variant
-      options = {
-        "event_category": data.category,
-        "event_label": data.label,
-        "value": data.value,
-        "non_interaction": true
-      }
-      options["send_to"] = @tracker_name if @tracker_name
-      window[@analytics_object_name]("event", data.action, options)
-    else
-      method_call_name =
-        if @tracker_name
-          "#{@tracker_name}.#{@send_method_name}"
-        else
-          @send_method_name
-      window[@analytics_object_name](
-        method_call_name, "event",
-        data.category, data.action, data.label, data.value,
-        {"nonInteraction": true}
-      )
-
-class GaEvents.GoogleAnalyticsAdapter
-  # https://developers.google.com/analytics/devguides/collection/gajs/eventTrackerGuide#SettingUpEventTracking
-  # Send events non_interactive => no influence on bounce rates
-  push: (data) ->
-    window._gaq.push(
-      ["_trackEvent", data.category, data.action, data.label, data.value, true]
-    )
+
+  push: (event_name, data) ->
+    data.send_to = @tracker_name if @tracker_name
+    window[@analytics_object_name]("event", event_name, data)
 
 class GaEvents.NullAdapter
-  push: (obj) -> console.log obj if console?
+  push: (event_name, data) -> console.log(event_name, data) if console?
+
+class GaEvents.GoogleTagManagerAdapter
+  constructor: (@event = "ga_event") ->
+
+  push: (event_name, data) ->
+    data.event = @event
+    data.event_name = event_name
+    data.non_interaction = true
+    window.dataLayer.push data
 
 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

@@ -27,6 +27,6 @@ Gem::Specification.new do |gem|
   gem.version       = GaEvents::VERSION
   gem.licenses      = ['MIT']
 
-  gem.required_ruby_version = '>= 2.3'
+  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 = '3.0.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: 3.0.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Florian Dütsch
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-01-10 00:00:00.000000000 Z
+date: 2023-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -49,6 +49,8 @@ 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
@@ -63,15 +65,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3.2'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project:
-rubygems_version: 2.7.6.2
+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
@@ -81,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