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' (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:



176
177
178
179
180
181
 
# File 'lib/piwik/site.rb', line 176

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
 
# 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})
  @id = result.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:



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

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.



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

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.



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

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.



101
102
103
 
# File 'lib/piwik/site.rb', line 101

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 



84
85
86
 
# File 'lib/piwik/site.rb', line 84

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:



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

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:



162
163
164
165
166
167
 
# File 'lib/piwik/site.rb', line 162

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:



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

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:



148
149
150
151
152
153
 
# File 'lib/piwik/site.rb', line 148

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