Description
Most of the applications we're working on are using some sort of tracking/analytics service,
Google Analytics comes first but its likely that more are added as the project grows.
Normally you'd go ahead and add some partials to your application that will render out the
needed tracking codes. As time passes by you'll find yourself with lots of tracking
snippets, that will clutter your codebase :) When just looking at Analytics there are
solutions like rack-google-analytics but they just soley tackle the existence of one
service.
We wanted a solution that ties all services together in one place and offers
an easy interface to drop in new services. This is why we created rack-tracker, a
rack middleware that can be hooked up to multiple services and exposing them in a unified
fashion. It comes in two parts, the first one is the actual middleware that you can add
to the middleware stack the second part are the service-handlers that you're going to use
in your application. It's easy to add your own custom handlers,
but to get you started we're shipping support for the following services out of the box:
Rack::Tracker alternatives and similar gems
Based on the "Analytics" category.
Alternatively, view Rack::Tracker alternatives based on common mentions on social networks and blogs.
-
Staccato
Ruby library to perform server-side tracking into the official Google Analytics Measurement Protocol -
The Chartable Ruby gem
A lightweight and database-level Ruby library to transform any Active Record query into analytics hash ready for use with any chart library. -
RailsUrlShortener
RailsUrlShortener is a lightweight Rails engine that enables easy creation and management of short URLs within your project. Similar to bitly.com, it condenses long links into short, user-friendly addresses. Enhance your app's functionality with this simple yet powerful URL shortening solution. -
RequestResponseStats
A Ruby gem which captures request response statistics such as cycle time, memory allocation, etc. for each request response cycle grouped in configurable granularity level. As this library makes use of TCP protocol, using DataDog or NewRelic RPM would be way faster because of UDP protocol.
Scout Monitoring - Performance metrics and, now, Logs Management Monitoring with Scout Monitoring
* Code Quality Rankings and insights are calculated and provided by Lumnify.
They vary from L1 to L5 with "L5" being the highest.
Do you think we are missing an alternative of Rack::Tracker or a related project?
README
Rack::Tracker
Rationale
Most of the applications we're working on are using some sort of tracking/analytics service,
Google Analytics comes first but its likely that more are added as the project grows.
Normally you'd go ahead and add some partials to your application that will render out the
needed tracking codes. As time passes by you'll find yourself with lots of tracking
snippets, that will clutter your codebase :) When just looking at Analytics there are
solutions like rack-google-analytics
but they just soley tackle the existence of one
service.
We wanted a solution that ties all services together in one place and offers
an easy interface to drop in new services. This is why we created rack-tracker
, a
rack middleware that can be hooked up to multiple services and exposing them in a unified
fashion. It comes in two parts, the first one is the actual middleware that you can add
to the middleware stack the second part are the service-handlers that you're going to use
in your application. It's easy to add your own custom handlers,
but to get you started we're shipping support for the services mentioned below
out of the box:
Respecting the Do Not Track (DNT) HTTP header
The Do Not Track (DNT) HTTP header is a HTTP header that requests the server to disable its tracking of the individual user. This is an opt-out option supported by most browsers. This option is disabled by default and has to be explicitly enabled to indicate the user's request to opt-out. We believe evey application should respect the user's choice to opt-out and respect this HTTP header.
Since version 2.0.0 rack-tracker respects that request header by default. That means NO tracker is injected IF the DNT header is set to "1".
This option can be overwriten using the DO_NOT_RESPECT_DNT_HEADER => true
option which must be set on any handler that should ignore the DNT header. (but please think twice before doing that)
Example on how to not respect the DNT header
use Rack::Tracker do
# this tracker will be injected EVEN IF the DNT header is set to 1
handler :maybe_a_friendly_tracker, { tracker: 'U-XXXXX-Y', DO_NOT_RESPECT_DNT_HEADER: true }
# this tracker will NOT be injected if the DNT header is set to 1
handler :google_analytics, { tracker: 'U-XXXXX-Y' }
end
Further reading on the DNT header:
Installation
Add this line to your application's Gemfile:
gem 'rack-tracker'
And then execute:
$ bundle
Or install it yourself as:
$ gem install rack-tracker
Usage
Add it to your middleware stack
config.middleware.use(Rack::Tracker) do
handler :google_analytics, { tracker: 'U-XXXXX-Y' }
end
This will add Google Analytics as a tracking handler.
Sinatra / Rack
You can even use Rack::Tracker with Sinatra or respectively with every Rack application
Just insert the Tracker in your Rack stack:
web = Rack::Builder.new do
use Rack::Tracker do
handler :google_analytics, { tracker: 'U-XXXXX-Y' }
end
run Sinatra::Web
end
run web
Although you cannot use the Rails controller extensions for obvious reasons, its easy to inject arbitrary events into the request environment.
request.env['tracker'] = {
'google_analytics' => [
{ 'class_name' => 'Send', 'category' => 'Users', 'action' => 'Login', 'label' => 'Standard' }
]
}
Services
Google Global Site Tag (gtag.js)
:anonymize_ip
- sets the tracker to remove the last octet from all IP addresses, see https://developers.google.com/analytics/devguides/collection/gtagjs/ip-anonymization for details.:cookie_domain
- sets the domain name for the GATC cookies. If not set its the website domain, with the www. prefix removed.:user_id
- defines a proc to set the userId. Ex:user_id: lambda { |env| env['rack.session']['user_id'] }
would return the user_id from the session.:link_attribution
- Enables Enhanced Link Attribution.:allow_display_features
- Can be used to disable Display Features.:custom_map
- Used to Configure and send custom dimensions:optimize_id
- Used to Deploy Optimize using gtag:set
- Used in the set command to configure multiple properties
Trackers
Google Global Site tag allows configuring multiple trackers. Use the tracker option to configure the ids:
config.middleware.use(Rack::Tracker) do
handler :google_global, { trackers: [ { id: 'U-XXXXX-Y' }, { id: 'U-WWWWWW-Z'} ] }
end
Google Analytics
:anonymize_ip
- sets the tracker to remove the last octet from all IP addresses, see https://developers.google.com/analytics/devguides/collection/gajs/methods/gaJSApi_gat?hl=de#_gat._anonymizeIp for details.:cookie_domain
- sets the domain name for the GATC cookies. If not set its the website domain, with the www. prefix removed.:user_id
- defines a proc to set the userId. Ex:user_id: lambda { |env| env['rack.session']['user_id'] }
would return the user_id from the session.:site_speed_sample_rate
- Defines a new sample set size for Site Speed data collection, see https://developers.google.com/analytics/devguides/collection/gajs/methods/gaJSApiBasicConfiguration?hl=de#_gat.GA_Tracker_._setSiteSpeedSampleRate:adjusted_bounce_rate_timeouts
- An array of times in seconds that the tracker will use to set timeouts for adjusted bounce rate tracking. See http://analytics.blogspot.ca/2012/07/tracking-adjusted-bounce-rate-in-google.html for details.:enhanced_link_attribution
- Enables Enhanced Link Attribution.:advertising
- Enables Display Features.:ecommerce
- Enables Ecommerce Tracking.:enhanced_ecommerce
- Enables Enhanced Ecommerce Tracking:optimize
- pass Google Optimize container ID as value (e.g.optimize: 'GTM-1234'
).:pageview_url_script
- a String containing a custom js script evaluating to the url that shoudl be given to the pageview event. Default towindow.location.pathname + window.location.search
.:explicit_pageview
- A boolean that controls whether to send thepageview
event on pageload. This defaults to true.
Events
To issue Events from the server side just call the tracker
method in your controller.
def show
tracker do |t|
t.google_analytics :send, { type: 'event', category: 'button', action: 'click', label: 'nav-buttons', value: 'X' }
end
end
It will render the following to the site source:
ga('send', { 'hitType': 'event', 'eventCategory': 'button', 'eventAction': 'click', 'eventLabel': 'nav-buttons', 'value': 'X' })
Parameters
You can set parameters in your controller too:
def show
tracker do |t|
t.google_analytics :parameter, { dimension1: 'pink' }
end
end
Will render this:
ga('set', 'dimension1', 'pink');
Enhanced Ecommerce
You can set parameters in your controller:
def show
tracker do |t|
t.google_analytics :enhanced_ecommerce, {
type: 'addItem',
id: '1234',
name: 'Fluffy Pink Bunnies',
sku: 'DD23444',
category: 'Party Toys',
price: '11.99',
quantity: '1'
}
end
end
Will render this:
ga("ec:addItem", {"id": "1234", "name": "Fluffy Pink Bunnies", "sku": "DD23444", "category": "Party Toys", "price": "11.99", "quantity": "1"});
Ecommerce
You can even trigger ecommerce directly from within your controller:
def show
tracker do |t|
t.google_analytics :ecommerce, { type: 'addItem', id: '1234', affiliation: 'Acme Clothing', revenue: '11.99', shipping: '5', tax: '1.29' }
end
end
Will give you this:
ga('ecommerce:addItem', { 'id': '1234', 'affiliation': 'Acme Clothing', 'revenue': '11.99', 'shipping': '5', 'tax': '1.29' })
To load the ecommerce
-plugin, add some configuration to the middleware initialization.
This is not needed for the above to work, but recommened, so you don't have to
take care of the plugin on your own.
config.middleware.use(Rack::Tracker) do
handler :google_analytics, { tracker: 'U-XXXXX-Y', ecommerce: true }
end
Google Adwords Conversion
You can configure the handler with default options:
config.middleware.use(Rack::Tracker) do
handler :google_adwords_conversion, { id: 123456,
language: "en",
format: "3",
color: "ffffff",
label: "Conversion label",
currency: "USD" }
end
To track adwords conversion from the server side just call the tracker
method in your controller.
def show
tracker do |t|
t.google_adwords_conversion :conversion, { value: 10.0 }
end
end
You can also specify a different value from default options:
def show
tracker do |t|
t.google_adwords_conversion :conversion, { id: 123456,
language: 'en',
format: '3',
color: 'ffffff',
label: 'Conversion Label',
value: 10.0 }
end
end
Google Tag Manager
Google Tag manager code snippet supports the container id
config.middleware.use(Rack::Tracker) do
handler :google_tag_manager, { container: 'GTM-XXXXXX' }
end
You can also use an experimental feature to track pageviews under turbolinks, which adds a pageView
event with a virtualUrl
of the current url.
config.middleware.use(Rack::Tracker) do
handler :google_tag_manager, { container: 'GTM-XXXXXX', turbolinks: true }
end
Data Layer
GTM supports a dataLayer for pushing events as well as variables.
To add events or variables to the dataLayer from the server side, just call the tracker
method in your controller.
def show
tracker do |t|
t.google_tag_manager :push, { price: 'X', another_variable: ['array', 'values'] }
end
end
Facebook Pixel
- adds the Facebook Pixel
Use in conjunction with the Facebook Helper to confirm your event fires correctly.
First, add the following to your config:
config.middleware.use(Rack::Tracker) do
handler :facebook_pixel, { id: 'PIXEL_ID' }
end
Dynamic Pixel Configuration
If you need to have different pixel ids e.g. based on the request or serving pages for different accounts, you have the possibility to achieve this by passing a lambda:
config.middleware.use(Rack::Tracker) do
handler :facebook_pixel, { id: lambda { |env| env['PIXEL_ID'] } }
end
and set the pixel id within the request env
variable. Here an example on how it can be done in a rails action:
class MyController < ApplicationController
def show
request.env['PIXEL_ID'] = 'DYNAMIC_PIXEL_ID'
end
end
Standard Events
To track Standard Events from the server side just call the tracker
method in your controller.
def show
tracker do |t|
t.facebook_pixel :track, { type: 'Purchase', options: { value: 100, currency: 'USD' } }
end
end
Will result in the following:
fbq("track", "Purchase", {"value":"100.0","currency":"USD"});
You can also use non-standard (custom) event names for audience building when you do not need to track or optimize for conversions.
tracker do |t|
t.facebook_pixel :track_custom, { type: 'FrequentShopper', options: { purchases: 24, category: 'Sport' } }
end
Visual website Optimizer (VWO)
Just integrate the handler with your matching account_id and you will be ready to go
use Rack::Tracker do
handler :vwo, { account_id: 'YOUR_ACCOUNT_ID' }
end
GoSquared
To enable GoSquared tracking:
config.middleware.use(Rack::Tracker) do
handler :go_squared, { tracker: 'ABCDEFGH' }
end
This will add the tracker to the page like so:
_gs('ABCDEFGH');
You can also set multiple named trackers if need be:
config.middleware.use(Rack::Tracker) do
handler :go_squared, {
trackers: {
primaryTracker: 'ABCDEFGH',
secondaryTracker: '1234567',
}
}
end
This will add the specified trackers to the page like so:
_gs('ABCDEFGH', 'primaryTracker');
_gs('1234567', 'secondaryTracker');
You can set a variety of options by passing the following settings. If you don't set any of the following options, they will be omitted from the rendered code.
:anonymize_ip
:cookie_domain
:use_cookies
:track_hash
:track_local
:track_params
Visitor Name
To track the visitor name from the server side, just call the tracker
method in your controller.
def show
tracker do |t|
t.go_squared :visitor_name, { name: 'John Doe' }
end
end
It will render the following to the site source:
_gs("set", "visitorName", "John Doe");
Visitor Properties
To track visitor properties from the server side, just call the tracker
method in your controller.
def show
tracker do |t|
t.go_squared :visitor_info, { age: 35, favorite_food: 'pizza' }
end
end
It will render the following to the site source:
_gs("set", "visitor", { "age": 35, "favorite_food": "pizza" });
Criteo
Criteo retargeting service.
Basic configuration
config.middleware.use(Rack::Tracker) do
handler :criteo, { set_account: '1234' }
end
Other global criteo handler options are:
set_customer_id: 'x'
set_site_type: 'd'
- possible values arem
(mobile),t
(tablet),d
(desktop)set_email: 'email'
Option values can be either static or dynamic by providing a lambda being reevaluated for each request, e.g. set_customer_id: lambda { |env| env['rack.session']['user_id'] }
Tracking events
This will track a basic event:
def show
tracker do |t|
t.criteo :view_item, { item: 'P0001' }
end
end
This will render to the follwing code in the JS:
window.criteo_q.push({"event": "viewItem", "item": "P001" });
The first argument for t.criteo
is always the criteo event (e.g. :view_item
, :view_list
, :track_transaction
, :view_basket
) and the second argument are additional properties for the event.
Another example
t.criteo :track_transaction, { id: 'id', item: { id: "P0038", price: "6.54", quantity: 1 } }
Zanox
Basic Configuration
config.middleware.use(Rack::Tracker) do
handler :zanox, { account_id: '1234' }
end
Mastertag
This is an example of a mastertag:
def show
tracker do |t|
t.zanox :mastertag, { id: "25GHTE9A07DF67DFG90T", category: 'Swimming', amount: '3.50' }
end
end
This will render to the follwing code in the JS:
window._zx.push({"id": "25GHTE9A07DF67DFG90T"});
and the following variables:
zx_category = 'Swimming';
zx_amount = '3.50';
Conversion tracking
This is an example of a lead event:
def show
tracker do |t|
t.zanox :lead, { order_i_d: 'DEFC-4321' }
end
end
This is an example of a sale event:
def show
tracker do |t|
t.zanox :sale, { customer_i_d: '123456', order_i_d: 'DEFC-4321', currency_symbol: 'EUR', total_price: '150.00' }
end
end
Hotjar
config.middleware.use(Rack::Tracker) do
handler :hotjar, { site_id: '1234' }
end
Bing
To add the tracking snippet:
config.middleware.use(Rack::Tracker) do
handler :bing, { tracker: '12345678' }
end
To send conversion events:
tracker do |t|
t.bing :conversion, {
type: 'event',
category: 'Users',
action: 'Login',
label: 'Standard',
value: 10
}
end
Hubspot
config.middleware.use(Rack::Tracker) do
handler :hubspot, { site_id: '1234' }
end
Drift
config.middleware.use(Rack::Tracker) do
handler :drift, account_id: 'DRIFT_ID'
end
Heap
Heap. Heap has Projects (e.g. "Main") which have multiple
Environments (e.g. "Production" or "Development"). env_id
is therefore the numerical ID
that represents the Environment. See Settings -> Projects -> Environments in your dashboard.
config.middleware.use(Rack::Tracker) do
handler :heap, env_id: 'HEAP_ID'
end
Custom Handlers
Tough we give you handlers for a few tracking services right out of the box, you might be interested adding support for your custom tracking/analytics service.
Writing a handler is straight forward ;) and there are just a couple of methods that your class needs to implement.
Start with a plain ruby class that inherits from Rack::Tracker::Handler
class MyHandler < Rack::Tracker::Handler
...
end
If you want to customize the rendering of your template, you can overwrite the handlers #render
method:
def render
Tilt.new( File.join( File.dirname(__FILE__), 'template', 'my_handler.erb') ).render(self)
end
There might be cases where you need to modify the response at multiple places. To do so you can overwrite the
#inject
-method in your handler. For an example please have a look at the Google Tag Manager implementation.
This will render the template/my_handler.erb
and inject the result into the source. You
can be creative about where the template is stored, but we tend to have them around
our actual handler code.
<script>
console.log('my tracker: ' + <%= options.to_json %>)
</script>
Lets give it a try! We need to mount our new handler in the Rack::Tracker
middleware
config.middleware.use(Rack::Tracker) do
handler MyHandler, { awesome: true }
end
Everything you're passing to the handler
will be available as #options
in your
template, so you'll also gain access to the env
-hash belonging to the current request.
Run your application and make a request, the result of the above template can be
found right before </head>
. You can change the position in your handler-code:
class MyHandler < Rack::Tracker::Handler
self.position = :body
...
end
The snippit will then be rendered right before </body>
.
To enable the tracker dsl functionality in your controllers
you need to implement the track
class method on your handler:
def self.track(name, *event)
# do something with the event(s) to prepare them for your template
# and return a hash with a signature like { name => event }
end
Checkout the existing handlers in lib/rack/tracker
for some inspiration. :)
Please note
Most tracking is done using some kind of Javascript and any tracking data is simply passed on. Using unvalidated user input in the tracking might result in XSS issues. Do only use secure data.
Contributing
First of all, thank you for your help! :green_heart:
If you want a feature implemented, the best way to get it done is to submit a pull request that implements it. Tests, readme and changelog entries would be nice.
- Fork it ( http://github.com/railslove/rack-tracker/fork )
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request