This is now the official Ruby client for Piwik. It completely covers the Piwik API and should be easily extendable by users. We made no assumptions on how you wanna use your data, so we closely mirrored Piwik's API structure even if it looks kinda weird to a modern rubyist.
We will also implement an extended
Piwik::Site wrapper class that will give you ruby-friendly access to a lot of the data in a way we think is sane, but it will be up to you which interface you want to use.
Please note that this release is not backward compatible. People using an older version of this gem should stick with version 0.6.1
- Simple ruby-friendly api
- Full API implementation
piwik-terminalbinary, allowing shell access.
- Works on MRI Jruby and RBX 1.8.* and 1.9.*
Add this line to your application's Gemfile:
gem 'autometal-piwik', :require => 'piwik'
And then execute:
Or install it yourself as:
$ gem install autometal-piwik
Use the binary
Open an extended irb session to a Piwik installation:
$ piwik-console -u http://demo.piwik.org -t anonymous :001 > Site.load 7 #=> #<Piwik::Site[snip]>
Unless you are using the binary, or if you are using the binary without credentials, you need to specify a url and a security token.
::PIWIK_URL = 'http://demo.piwik.org' ::PIWIK_TOKEN = 'anonymous'
This can take place in your script or a rails initializer or whatever.
Use the wrapper class
Fastest way to get to know the client is by using the Piwik::Site wrapper class:
site = ::.(7) #=> #<Piwik::Site[snip]> site.annotations.all #=> #<Piwik::Annotations[snip]> site.annotations.add(:date => 'today', :starred => 1) #=> Piwik::ApiError: Please specify a value for 'note'. site.annotations.add(:note => 'meep', :date => 'today', :starred => 1) #=> #<Piwik::Annotations[snip]> summary = site.actions.summary #=> #<Piwik::Actions[snip]> summary.nb_pageviews #=> 236 summary.nb_uniq_pageviews #=> 170
Not all methods are implemented on the wrapper class, although if you find yourself adding methods, please submit a pull request. You can have a look at site_spec.rb for an up-to-date list of available methods.
Use the 'native' API
This client also allows you to interact with the API the way its designers wanted it. Any method in the api reference is made available almost verbatim:
# http://piwik.org/docs/analytics-api/reference/#Actions # Actions.getPageUrls (idSite, period, date, segment = '', expanded = '', idSubtable = '') require 'rubygems' require 'piwik' ::PIWIK_URL = 'http://demo.piwik.org' ::PIWIK_TOKEN = 'anonymous' ::.getPageUrls(:idSite => 7, :period => :day, :date => 'yesterday') #=> #<Piwik::Actions::PageUrls @data=[snip]>
That last call is exactly the same as calling
site.actions.page_urls(:period => :day, :date => 'yesterday')
It is probably apparent, but the second way gives you full access to everything, all you need is the API reference and you're off. If you are simply after displaying the basic analytics values for a site, the wrapper is probably the way to go.
- Fork it
- 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