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

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_from_file
  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_from_file
  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:



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

def actions(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  xml = call('VisitsSummary.getActions', :idSite => id, :period => period, :date => date)
  result = XmlSimple.xml_in(xml, {'ForceArray' => false})
  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
70
71
72
73
74
75
 
# 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?
  xml = call('SitesManager.addSite', :siteName => name, :urls => main_url)
  result = XmlSimple.xml_in(xml, {'ForceArray' => false})
  case result.class
  when Hash
    @id = result["result"].to_i
  else
    @id = result.to_i
  end
  @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:



96
97
98
99
100
101
102
 
# File 'lib/piwik/site.rb', line 96

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

#give_admin_access_to(login) ⇒ Object

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



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

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.



118
119
120
 
# File 'lib/piwik/site.rb', line 118

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.



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

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 



89
90
91
 
# File 'lib/piwik/site.rb', line 89

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:



132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/piwik/site.rb', line 132

def summary(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  xml = call('VisitsSummary.get', :idSite => id, :period => period, :date => date)
  result = XmlSimple.xml_in(xml, {'ForceArray' => false})
  {
    :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:



167
168
169
170
171
172
 
# File 'lib/piwik/site.rb', line 167

def unique_visitors(period=:day, date=Date.today)
  raise UnknownSite, "Site not existent in Piwik yet, call 'save' first" if new?
  xml = call('VisitsSummary.getUniqueVisitors', :idSite => id, :period => period, :date => date)
  result = XmlSimple.xml_in(xml, {'ForceArray' => false})
  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:



80
81
82
83
84
85
86
87
 
# File 'lib/piwik/site.rb', line 80

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?
  xml = call('SitesManager.updateSite', :idSite => id, :siteName => name, :urls => main_url)
  result = XmlSimple.xml_in(xml, {'ForceArray' => false})
  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:



153
154
155
156
157
158
 
# File 'lib/piwik/site.rb', line 153

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