Skip to content

Nix-wie-weg/ga_events

master
Switch branches/tags
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
lib
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

GaEvents

Use Google Analytics' Event Tracking everywhere in your Rails app!

This gem alllows you to annotate events everywhere in the code of your Rails 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. 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.

Dependencies

  • Ruby >= 2.3
  • Rails 4.2 onwards
  • jQuery

Installation

Add it to your Gemfile with:

gem 'ga_events'

Run the bundle command to install it.

Add to the top of your application.js (but after requiring jQuery):

//= require ga_events.js

After requiring ga_events.js, you have to choose an adapter.

Google Analytics (ga.js)

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleAnalyticsAdapter();
}

Google Universal Analytics

analytics.js

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleUniversalAnalyticsAdapter();
}

Optionally you can specify a custom send method to call and a custom tracker name:

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleUniversalAnalyticsAdapter(
    {send_method_name: "sendNow", tracker_name: "customTracker"}
  );
}

gtag.js

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleUniversalAnalyticsAdapter(
    {use_gtag_variant: true}
  );
}

Optionally you can specify a custom tracker GA_MEASUREMENT_ID where you want your events to be sent to:

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleUniversalAnalyticsAdapter(
    {use_gtag_variant: true, 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:

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleUniversalAnalyticsAdapter(
    {analytics_object_name: "analytics"} // calls window.analytics()
  );
}

Google TagManager

If you are using Google Tag Manager you can add custom events which are then passed through to Google Analytics.

GaEvents.Event.adapter = function() {
  return new GaEvents.GoogleTagManagerAdapter("event_name"); // defaults to ga_event
}

Optional consent settings

Events are flushed immediatly by default. If you need to wait for user consent you can set GaEvents.Event.require_user_consent = true.

With require_user_consent enabled all events are buffered until GaEvents.Event.user_consent_given = true is set. Events are flushed as soon as GaEvents.Event.flush() is called.

Testing

For your testing pleasure we included NullAdapter.

GaEvents.Event.adapter = function() {
  return new GaEvents.NullAdapter();
}

Usage

On the server-side a new event is added to a list, serialized into a container element and then added to your HTML response. On Ajax requests a custom HTTP header is added to the response.

You can create a new event like this:

GaEvents::Event.new(category, action, label, value)

On the client-side there is a similar interface to GaEvents:

new GaEvents.Event(category, action, label, value)

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 event data:

class ApplicationController < ActionController::Base
  after_filter :too_many_ga_events?
  private
  def too_many_ga_events?
    if (serialized = GaEvents::List.to_s).length > 1_024
      notify("GaEvents too big: #{serialized}")
    end
    true
  end
end

Testing

Middlewares aren't loaded in controller specs, so you have to initialize GaEvents by hand. You can do this eg. in your spec_helper.rb:

RSpec.configure do |config|
  [...]
  config.before(:each, type: :controller) do
    GaEvents::List.init
  end
end

Contributing

Yes please! Use pull requests.

Credits

More docs and tools

About

Google Analytics' Event Tracking everywhere in your Rails app

Resources

License

Stars

Watchers

Forks

Packages

No packages published