Class: Piwik::Site

Inherits:
Base
  • Object
show all
Defined in:
lib/piwik/site.rb

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

config_file, parse_json, #parse_json

Constructor Details

#initialize(attributes = {}, piwik_url = nil, auth_token = nil) ⇒ Site

Initializes a new Piwik::Site object, with the supplied attributes.

You can pass the URL for your Piwik install and an authorization token as the second and third parameters. If you don’t, than it will try to find them in a '~/.piwik' or RAILS_ROOT/config/piwik.yml (and create the file with an empty template if it doesn’t exists).

Valid (and required) attributes are:

  • :name - the site’s name

  • :main_url - the site’s url

Raises:

  • (ArgumentError) 


16
17
18
19
20
21
22
23
24
 
# File 'lib/piwik/site.rb', line 16

def initialize(attributes={}, piwik_url=nil, auth_token=nil)
  raise ArgumentError, "expected an attributes Hash, got #{attributes.inspect}" unless attributes.is_a?(Hash)
  @config = if piwik_url.nil? || auth_token.nil?
    self.class.load_config
  else
    {:piwik_url => piwik_url, :auth_token => auth_token}
  end
  load_attributes(attributes)
end

Instance Attribute Details

#config ⇒ Object (readonly)

Returns the value of attribute config.



4
5
6
 
# File 'lib/piwik/site.rb', line 4

def config
  @config
end

#created_at ⇒ Object (readonly)

Returns the value of attribute created_at.



4
5
6
 
# File 'lib/piwik/site.rb', line 4

def created_at
  @created_at
end

#id ⇒ Object (readonly)

Returns the value of attribute id.



4
5
6
 
# File 'lib/piwik/site.rb', line 4

def id
  @id
end

#main_url ⇒ Object

Returns the value of attribute main_url.



3
4
5
 
# File 'lib/piwik/site.rb', line 3

def main_url
  @main_url
end

#name ⇒ Object

Returns the value of attribute name.



3
4
5
 
# File 'lib/piwik/site.rb', line 3

def name
  @name
end

Class Method Details

.load(site_id, piwik_url = nil, auth_token = nil) ⇒ Object

Returns an instance of Piwik::Site representing the site identified by the supplied site_id. Raises a Piwik::ApiError if the site doesn’t exists or if the user associated with the supplied auth_token does not have at least ‘view’ access to the site.

You can pass the URL for your Piwik install and an authorization token as the second and third parameters. If you don’t, than it will try to find them in a '~/.piwik' (and create the file with an empty template if it doesn’t exists).

Raises:

  • (ArgumentError) 


35
36
37
38
39
40
41
42
43
44
 
# File 'lib/piwik/site.rb', line 35

def self.load(site_id, piwik_url=nil, auth_token=nil)
  raise ArgumentError, "expected a site Id" if site_id.nil?
  @config = if piwik_url.nil? || auth_token.nil?
    load_config
  else
    {:piwik_url => piwik_url, :auth_token => auth_token}
  end
  attributes = get_site_attributes_by_id(site_id, @config[:piwik_url], @config[:auth_token])
  new(attributes, @config[:piwik_url], @config[:auth_token])
end

Instance Method Details

#actions(period = :day, date = Date.today) ⇒ Object Also known as: pageviews

Returns the amount of actions (pageviews) for the current site, filtered by the supplied period and date.

  • period should be one of :day, :week, :month or :year (default: :day)

  • date should be a Date object (default: Date.today)

Equivalent Piwik API call: VisitsSummary.getActions (idSite, period, date)

Raises:



172
173
174
175
176
 
# File 'lib/piwik/site.rb', line 172

def actions(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('VisitsSummary.getActions', :idSite => id, :period => period, :date => date)
  result.to_i
end

#create ⇒ Object

Saves the current new site in Piwik.

Equivalent Piwik API call: SitesManager.addSite (siteName, urls)

Raises:

  • (ArgumentError) 


61
62
63
64
65
66
67
68
69
 
# File 'lib/piwik/site.rb', line 61

def create
  raise ArgumentError, "Site already exists in Piwik, call 'update' instead" unless new?
  raise ArgumentError, "Name can not be blank" if name.blank?
  raise ArgumentError, "Main URL can not be blank" if main_url.blank?
  result = call('SitesManager.addSite', :siteName => name, :urls => main_url)
  @id = result['value'].to_i
  @created_at = Time.current
  id && id > 0 ? true : false
end

#destroy ⇒ Object

Deletes the current site from Piwik.

Equivalent Piwik API call: SitesManager.deleteSite (idSite)

Raises:



89
90
91
92
93
94
95
 
# File 'lib/piwik/site.rb', line 89

def destroy
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('SitesManager.deleteSite', :idSite => id)
  #puts "\n destroy #{result} \n"
  freeze
  result['result'] == 'success' ? true : false
end

#get_javascript_tag ⇒ Object

Returns a string with the javascript tracking code for the current site.

Equivalent Piwik API call: SitesManager.getJavascriptTag (idSite)

Raises:



182
183
184
185
186
187
 
# File 'lib/piwik/site.rb', line 182

def get_javascript_tag
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('SitesManager.getJavascriptTag', :idSite => id)
  #puts "get_javascript_tag #{result.to_s}"
  result['value']
end

#get_page_titles(params = {}) ⇒ Object

Returns a big Array of Hashes with all page titles along with standard Actions metrics for each row, for the current site.

Example result:

> [Izdelava spletnih strani | Spletnik d.o.o.”, “nb_visits”=>36, “nb_uniq_visitors”=>35, “nb_hits”=>41, “sum_time_spent”=>240, “entry_nb_uniq_visitors”=>“33”, “entry_nb_visits”=>“36”, “entry_nb_actions”=>“92”, “entry_sum_visit_length”=>“3422”, “entry_bounce_count”=>“20”, “exit_nb_uniq_visitors”=>“19”, “exit_nb_visits”=>“22”, “avg_time_on_page”=>7, “bounce_rate”=>“56%”, “exit_rate”=>“61%”]

Equivalent Piwik API call: Actions.getPageTitles (idSite, period, date, segment = ”, expanded = ”, idSubtable = ”)

Raises:



195
196
197
198
199
200
 
# File 'lib/piwik/site.rb', line 195

def get_page_titles(params={})
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('Actions.getPageTitles', {:idSite => id, :period => :day, :date => Date.today, :segment => '', :expanded => '', :idSubtable => ''}.update(params))
  #puts "get_page_titles: #{result}"
  result
end

#get_page_urls(params = {}) ⇒ Object

Returns a big Array of Hashes with all page urls along with standard Actions metrics for each row, for the current site.

Example result:

> [“nb_visits”=>69, “nb_hits”=>87, “sum_time_spent”=>4762, “entry_nb_visits”=>40, “entry_nb_actions”=>101, “entry_sum_visit_length”=>6752, “entry_bounce_count”=>26, “exit_nb_visits”=>39, “avg_time_on_page”=>69, “bounce_rate”=>“65%”, “exit_rate”=>“57%”, “idsubdatatable”=>1]

Example call:

Piwik::Site.load(203).get_page_urls(:expanded=>1)

Equivalent Piwik API call: Actions.getPageUrls (idSite, period, date, segment = ”, expanded = ”, idSubtable = ”)

Raises:



212
213
214
215
216
217
 
# File 'lib/piwik/site.rb', line 212

def get_page_urls(params={})
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('Actions.getPageUrls', { :idSite => id, :period => :day, :date => Date.today, :segment => '', :expanded => '', :idSubtable => '' }.update(params))
  #puts "get_page_urls: #{result}"
  result
end

#give_admin_access_to(login) ⇒ Object

Gives read and write access ('admin') for the supplied user login for the current site.



105
106
107
 
# File 'lib/piwik/site.rb', line 105

def give_admin_access_to()
  give_access_to(:admin, )
end

#give_no_access_to(login) ⇒ Object Also known as: remove_access_from

Removes all access (gives an 'noaccess') for the supplied user login for the current site.



111
112
113
 
# File 'lib/piwik/site.rb', line 111

def give_no_access_to()
  give_access_to(:noaccess, )
end

#give_view_access_to(login) ⇒ Object

Gives read access ('view') to the supplied user login for the current site.



99
100
101
 
# File 'lib/piwik/site.rb', line 99

def give_view_access_to()
  give_access_to(:view, )
end

#new? ⇒ Boolean

Returns true if the current site does not exists in the Piwik yet.

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/piwik/site.rb', line 47

def new?
  id.nil? && created_at.nil?
end

#reload ⇒ Object 



82
83
84
 
# File 'lib/piwik/site.rb', line 82

def reload
  #TODO
end

#save ⇒ Object

Saves the current site in Piwik.

Calls create it it’s a new site, update otherwise.



54
55
56
 
# File 'lib/piwik/site.rb', line 54

def save
  new? ? create : update
end

#summary(period = :day, date = Date.today) ⇒ Object

Returns a hash with a summary of access information for the current site (visits, unique visitors, actions / pageviews, maximum actions per visit, bounces and total time spent in all visits in seconds), filtered by the supplied period and date.

  • period should be one of :day, :week, :month or :year (default: :day)

  • date should be a Date object (default: Date.today)

Equivalent Piwik API call: VisitsSummary.get (idSite, period, date)

Raises:



126
127
128
129
130
131
132
133
134
135
136
137
 
# File 'lib/piwik/site.rb', line 126

def summary(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('VisitsSummary.get', :idSite => id, :period => period, :date => date)
  {
    :visits => result['nb_visits'].to_i,
    :unique_visitors => result['nb_uniq_visitors'].to_i,
    :actions => result['nb_actions'].to_i,
    :max_actions_per_visit => result['max_actions'].to_i,
    :bounces => result['bounce_count'].to_i,
    :total_time_spent => result['sum_visit_length'].to_i, # in seconds
  }
end

#unique_visitors(period = :day, date = Date.today) ⇒ Object

Returns the amount of unique visitors for the current site, filtered by the supplied period and date.

  • period should be one of :day, :week, :month or :year (default: :day)

  • date should be a Date object (default: Date.today)

Equivalent Piwik API call: VisitsSummary.getUniqueVisitors (idSite, period, date)

Raises:



159
160
161
162
163
 
# File 'lib/piwik/site.rb', line 159

def unique_visitors(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('VisitsSummary.getUniqueVisitors', :idSite => id, :period => period, :date => date)
  result.to_i
end

#update ⇒ Object

Saves the current site in Piwik, updating it’s data.

Equivalent Piwik API call: SitesManager.updateSite (idSite, siteName, urls)

Raises:



74
75
76
77
78
79
80
 
# File 'lib/piwik/site.rb', line 74

def update
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  raise ArgumentError, "Name can not be blank" if name.blank?
  raise ArgumentError, "Main URL can not be blank" if main_url.blank?
  result = call('SitesManager.updateSite', :idSite => id, :siteName => name, :urls => main_url)
  result['result'] == 'success' ? true : false
end

#visits(period = :day, date = Date.today) ⇒ Object

Returns the amount of visits for the current site, filtered by the supplied period and date.

  • period should be one of :day, :week, :month or :year (default: :day)

  • date should be a Date object (default: Date.today)

Equivalent Piwik API call: VisitsSummary.getVisits (idSite, period, date)

Raises:



146
147
148
149
150
 
# File 'lib/piwik/site.rb', line 146

def visits(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  result = call('VisitsSummary.getVisits', :idSite => id, :period => period, :date => date)
  result.to_i
end