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.
+
[](http://badge.fury.io/rb/staccato)
[](https://travis-ci.org/tpitale/staccato)
[](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