README.md in staccato-0.0.4 vs README.md in staccato-0.1.0

- old
+ new

@@ -1,13 +1,18 @@ # Staccato -Ruby Google Analytics Measurement +Ruby library to track into the official Google Analytics Measurement Protocol +https://developers.google.com/analytics/devguides/collection/protocol/v1/ + +**NOTE:** The Measurement Protocol is part of Universal Analytics, which is currently available in public beta. Data from the measurement protocol will only be processed in Universal Analytics enabled properties. + [![Gem Version](https://badge.fury.io/rb/staccato.png)](http://badge.fury.io/rb/staccato) [![Build Status](https://travis-ci.org/tpitale/staccato.png?branch=master)](https://travis-ci.org/tpitale/staccato) [![Code Climate](https://codeclimate.com/github/tpitale/staccato.png)](https://codeclimate.com/github/tpitale/staccato) + ## Installation Add this line to your application's Gemfile: gem 'staccato' @@ -71,22 +76,74 @@ variation: 'red', currency: 'EUR' }) ``` -Each one of these methods returns a particular `hit` type. To send the tracking information to google analytics, simply call `track!`. +### "Global" Options ### +Any of the options on the parameters list (https://developers.google.com/analytics/devguides/collection/protocol/v1/parameters) that are accepted on ALL hit types can be set as options on any of the hits. + ```ruby -tracker.pageview(path: '/item-120291').track! +tracker.pageview(path: '/video/1235', flash_version: 'v1.2.3') ``` -### "Global" Options ### +Flash Version is a global option in the example above. +**Note:** There are a few options that if used will override global options: + +* document_path: overriden by `path` in pageviews +* document_hostname: overriden by `hostname` in pageviews +* document_title: overriden by `title` in pageviews + +These are holdovers from the original design, where `pageview` is a hit type that can take any/all of the optional parameters. `path`, `hostname`, and `title` are slightly nicer to use on `pageview`. + +The complete list at this time: + +```ruby +Staccato::Hit::GLOBAL_OPTIONS.keys # => + +[:anonymize_ip, + :queue_time, + :cache_buster, + :user_id, + :user_ip, + :user_agent, + :referrer, + :campaign_name, + :campaign_source, + :campaign_medium, + :campaign_keyword, + :campaign_content, + :campaign_id, + :adwords_id, + :display_ads_id, + :screen_resolution, + :viewport_size, + :screen_colors, + :user_language, + :java_enabled, + :flash_version, + :document_location, + :document_encoding, + :document_hostname, + :document_path, + :document_title, + :link_id, + :application_name, + :application_version, + :application_id, + :application_installer_id, + :experiment_id, + :experiment_variant] +``` + +Boolean options like `anonymize_ip` will be converted from `true`/`false` into `1`/`0` as per the tracking API docs. + #### Custom Dimensions and Metrics #### ```ruby -hit = tracker.pageview('/sports-page-5') +hit = Staccato::Pageview.new(tracker, '/sports-page-5') hit.add_custom_dimension(19, 'Sports') hit.add_custom_metric(2, 5) hit.track! ``` @@ -126,9 +183,22 @@ tracker.pageview({ path: '/blog', experiment_id: 'a7a8d91df', experiment_variant: 'a' }) +``` + +## Tracker Hit Defaults ## + +Global parameters can be set as defaults on the tracker, and will be used for all hits (unless overwritten by parameters set directly on a hit). + +The following example creates a tracker with a default hostname. The two pageviews will track the default hostname and the page path passed in. + +```ruby +tracker = Staccato.tracker('UA-XXXX-Y', client_id, {document_hostname: 'example.com'}) + +tracker.pageview(path: '/videos/123') +tracker.pageview(path: '/videos/987') ``` ## Google Documentation https://developers.google.com/analytics/devguides/collection/protocol/v1/devguide