Plug-and-play Rails engine for tracking your visitors’ IP address, the ad campaign where they came from, their browser, or the referring website.

See: Github README for complete details and code.

About

Universal Track Manager, also known as UTM, is a gem to track your visitors and their pageloads. You can use it to track Urchin Tracking Module (UTM) parameters, and the fact that these two things abbreviate to the same letters is play-on-words.

You can use Universal Track Manager to track simple information like browser, IP address, http referrer, and your inbound UTM (Urchin Tracking Module) parameters. Because UTM parameters are used most commonly with advirtising, we also refer to tracking your UTM parameters as “ad campaigns” or just “campaigns”.

In particular, this Gem can be used to solve the common first-land problem where UTM parameters are present only in the first page of a user’s visit, but not available naturally a few steps later when the event you want to track happens (see ‘UTM Hooks’)

Visits are a lot like Rails sessions; in fact, this Gem piggybacks off of Rails sessions for tracking the visit. (You will need to have a session store set up and in place.)

However, visits are not identical to sessions. More than one visit can have been created from the same session.

A session will have only one visit at a time. If a new visit event happens within an existing session, like the user returns in the same browser the following day, the old visit gets evicted from the session and a link between the newly created visit and old visit is maintained in the visits table.

Is this Ethical?

It is important to understand there are many different data points can could possibly be collected in today’s web traffic. You may use this gem at your own discretion, and you can choose either more or less data capturing, as well ore more or less data integration with your users.

The reason I underscore this point is that the safest data is anonymized data.

The general Rails best practice for the last decade has been to keep only session data with the user, but anonymize identifying data (like IP, behavior, browser), which could be used to identify individual users.

Please see the section ‘Granularity of Data Capture’ to understand the many different levels of (non-)privacy you may choose as the website operators.

Is this Legal?

In any country or region where a privacy law like the GDPR or California Consumer Privacy Act is in effect, getting informed consent to track this information is just one part of what you must do to comply with the law.

Most privacy laws regulate the usage, storage, transmission, and removal of this data once you are retaining it in your database as well.

This gem express captures this data, as described in this README document, and by using this gem you are responsible for complying with the appropriate laws and regulations subject to you.

You will note that most old privacy policies talk about much of this data being stored in “log files.” This gem takes the data retention farther and stores the data into the database. (So you should modify your privacy policy accordingly.)

Please consult a legal expert familiar with the laws of your region regarding data retention and capture if you are going to use this gem.

Installation

Please familiarize yourself with the concepts above before installing.

1. add gem 'universal-track-manager' to your Gemfile
2. run

rails generate universal_track_manager:install

This will create a schema migration for the new tables that UTM will use (look for db/migrate/00000000000000_create_universal_tracking_manager_tables.rb. see ‘Name Conflicts’ below if any of these tables already exist in your app.)

3. In your ApplicationController, add:

  include UniversalTrackManagerConcern

4. Notice tha the installer has created this file for you in config/initializers/universal_track_manager.rb

UniversalTrackManager.configure do |config|
  config.track_ips = true
  config.track_utms = true
  config.track_user_agent = true
  config.campaign_columns = 'utm_source,utm_medium,utm_campaign,utm_content,utm_term'
  # config.track_referrer = false
end

(Notice track_referrer is disable by default

5. Extensible UTMs As of Version 0.7, you can now extend the UTM parameters to include any paramater with data for your website’s inbound traffic. This is useful if you are running advertising that brings people to your Rails site and the ad platforms are sending you traffic with specific, custom tracking parameters you want to keep track of.

To customize, modify the comma-separated config.campaign_columns in the initializer above.

Options

Configuration options can be set in config/initializers/universal_track_manager.rb which will automatically be created for you when you run the install generator. Set any option to false to disable tracking.

UTM Hooks

Note that in this section we are talking about the Urchin Tracking Module (also, non-coincidtally, abbreviated as UTMs). These appear on your inbound links as GET parameters and look like:

utm_source
utm_campaign
utm_medium
utm_term
utm_content

For example, a typical inbound link with fully coded UTM parameters might look like so:

https://www.example.com/page?utm_content=buffercf3b2&utm_medium=social&utm_source=facebook.com&utm_campaign=buffer

When a visitor first lands on your site, the UTMs from that first land are assocaited to the visit (we will call these the first-land UTMs). From here, your visitor might click to a second page, or a third page, before signing up or logging in. By this time, the UTMs are no longer stored in the URL parameters because the user has clicked several pages into your website.

As the web operator, you want to know which of your advirtising campaigns are leading to which sign-ups or logins. One common approach is to store the UTMs in the session until the user signs up or logs in.

Using this gem, we do not store the UTMs in the session, but instead the session has a link to the visits table that can used later (upon the event where you want to capture the UTMs).

If you want to grab your UTMs them from Universal Track Manager object, support is already biult-in easily from any controller:

currrent_track.campaign

You can also fetch and store the currrent_track.campaign_id in your foreign table, which will allow you to aggregate your tracked events to your the inbound traffic sources. Remember, this Gem will not do this for you as you must associate this to your application’s own unique needs. Please note that nil is nil in the database and empty string is empty string. if campaign parameters are attached to inbound links as empty string, they will create distinct records from those where no parameter was passed