Class: Forem::Analytics

Inherits:
APIResource show all
Defined in:
lib/forem/resources/analytics.rb

Overview

Provides access to analytics data for the authenticated user's content.

All analytics endpoints require authentication. They return analytics for the calling user (or an organization, when :organization_id is passed).

The Analytics resource exposes four read-only reporting endpoints: cumulative totals, day-by-day historical data, yesterday's aggregates, and traffic referrer breakdowns.

Response shapes

The Forem analytics endpoints don't all return the same kind of object, so this resource preserves each endpoint's natural shape rather than forcing them into a uniform list:

Examples:

Lifetime totals

totals = client.analytics.totals
puts totals.reactions.total   #=> 7
puts totals.page_views.total  #=> 7

Historical data for a date range

history = client.analytics.historical(start: "2026-04-01", end: "2026-04-30")
history.each do |date, stats|
  puts "#{date}: #{stats.page_views.total} views"
end

Referrer breakdown

client.analytics.referrers.each { |r| puts "#{r.domain}: #{r.count}" }

See Also:

Constant Summary collapse

OBJECT_NAME = 
"analytics"
RESOURCE_PATH = 
"/api/analytics"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Class Method Summary collapse

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from Forem::APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Class Method Details

.historical(params = {}, opts = {}) ⇒ Hash{String => Forem::ForemObject}

Return day-by-day historical analytics for a given date range.

The response is a Hash keyed by the calendar date (+"YYYY-MM-DD"+). Each value is a stats object with the same nested shape as totals.

Examples:

history = client.analytics.historical(start: "2026-04-01", end: "2026-04-15")
history.each do |date, stats|
  puts "#{date}: #{stats.page_views.total} views"
end

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :start (String) — default: required —

    start date in YYYY-MM-DD form.

  • :end (String) —

    end date in YYYY-MM-DD form.

  • :article_id (String) —

    filter to a specific article.

  • :organization_id (Integer) —

    ID of the organization.

Returns:

See Also:



83
84
85
86
87
 
# File 'lib/forem/resources/analytics.rb', line 83

def self.historical(params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/analytics/historical", params, opts)
  grouped_by_day(resp.parsed_body, requestor)
end

.past_day(params = {}, opts = {}) ⇒ Hash{String => Forem::ForemObject}

Return aggregated analytics for the previous calendar day(s).

The response shape mirrors historical: a Hash keyed by date. Forem typically returns one or two entries (yesterday plus today's partial), so callers usually want either the most recent date or iteration with #each.

Examples:

stats = client.analytics.past_day
latest_date, latest_stats = stats.max_by { |date, _| date }
puts "#{latest_date}: #{latest_stats.page_views.total} views"

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :article_id (String) —

    filter to a specific article.

  • :organization_id (Integer) —

    ID of the organization.

Returns:

See Also:



106
107
108
109
110
 
# File 'lib/forem/resources/analytics.rb', line 106

def self.past_day(params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/analytics/past_day", params, opts)
  grouped_by_day(resp.parsed_body, requestor)
end

.referrers(params = {}, opts = {}) ⇒ Array<Forem::ForemObject>

Return the breakdown of traffic referrers for the authenticated user's content.

The endpoint wraps the data in a {"domains" => [...]} envelope. This method unwraps that envelope and returns the inner array directly so callers can iterate without an extra hop.

Examples:

client.analytics.referrers.each { |r| puts "#{r.domain}: #{r.count}" }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :start (String) —

    start date in YYYY-MM-DD form.

  • :end (String) —

    end date in YYYY-MM-DD form.

  • :article_id (String) —

    filter to a specific article.

  • :organization_id (Integer) —

    ID of the organization.

Returns:

See Also:



130
131
132
133
134
135
136
 
# File 'lib/forem/resources/analytics.rb', line 130

def self.referrers(params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/analytics/referrers", params, opts)
  body = resp.parsed_body
  domains = body.is_a?(Hash) ? (body["domains"] || []) : []
  domains.map { |item| Forem::ForemObject.construct_from(item, requestor: requestor) }
end

.totals(params = {}, opts = {}) ⇒ Forem::ForemObject

Return cumulative analytics totals for the authenticated user (or org).

The response groups totals into nested buckets — comments, follows, reactions, and page_views — each with its own sub-fields. To read a count, navigate one level deeper than you might expect (e.g. totals.reactions.total, not totals.reactions).

Examples:

totals = client.analytics.totals
puts totals.reactions.total          #=> 7
puts totals.reactions.like           #=> 2
puts totals.page_views.total         #=> 7

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options

Options Hash (params):

  • :article_id (String) —

    filter to a specific article

  • :organization_id (Integer) —

    ID of the organization

Returns:

See Also:



59
60
61
62
63
 
# File 'lib/forem/resources/analytics.rb', line 59

def self.totals(params = {}, opts = {})
  requestor = opts[:requestor]
  resp = request(:get, "/api/analytics/totals", params, opts)
  Forem::ForemObject.construct_from(resp.parsed_body, requestor: requestor)
end