Documentation
¶
Overview ¶
Package analytics_int provides built-in server-side analytics for oCMS. It tracks page views, unique visitors, referrers, browser/device stats, and geographic data with privacy-focused anonymization.
Index ¶
- func CountryName(code string) string
- type BrowserStat
- type CountryStat
- type DailyStat
- type DashboardData
- type DeviceStat
- type GeoIPLookup
- type GeoStat
- type HourlyStat
- type Module
- func (m *Module) AdminURL() string
- func (m *Module) CreateSessionHash(ip, userAgent string) string
- func (m *Module) CreateVisitorHash(ip, userAgent string) string
- func (m *Module) GetRealTimeVisitorCount(minutes int) int
- func (m *Module) GetTrackingMiddleware() func(next http.Handler) http.Handler
- func (m *Module) Init(ctx *module.Context) error
- func (m *Module) IsEnabled() bool
- func (m *Module) Migrations() []module.Migration
- func (m *Module) RegisterAdminRoutes(r chi.Router)
- func (m *Module) RegisterRoutes(_ chi.Router)
- func (m *Module) ReloadSettings() error
- func (m *Module) RunAggregationNow() error
- func (m *Module) RunFullAggregation(ctx context.Context) (int, error)
- func (m *Module) Shutdown() error
- func (m *Module) SidebarLabel() string
- func (m *Module) StartAggregator()
- func (m *Module) TemplateFuncs() template.FuncMap
- func (m *Module) TrackingMiddleware() func(http.Handler) http.Handler
- func (m *Module) TranslationsFS() embed.FS
- type OverviewStats
- type PageView
- type ParsedUA
- type ReferrerStat
- type Settings
- type TechStat
- type TimeSeriesPoint
- type TopPage
- type TopReferrer
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CountryName ¶
CountryName returns the full country name for a 2-letter country code.
Types ¶
type BrowserStat ¶
BrowserStat represents browser breakdown for dashboard.
type CountryStat ¶
CountryStat represents country breakdown for dashboard.
type DailyStat ¶
type DailyStat struct {
ID int64
Date time.Time
Path string
Views int
UniqueVisitors int
Bounces int
}
DailyStat represents daily aggregated statistics.
type DashboardData ¶
type DashboardData struct {
Overview OverviewStats
TopPages []TopPage
TopReferrers []TopReferrer
Browsers []BrowserStat
Devices []DeviceStat
Countries []CountryStat
TimeSeries []TimeSeriesPoint
DateRange string // "7d", "30d", "90d", "1y"
Settings Settings
}
DashboardData contains all data for the analytics dashboard.
type DeviceStat ¶
DeviceStat represents device type breakdown for dashboard.
type GeoIPLookup ¶
type GeoIPLookup struct {
// contains filtered or unexported fields
}
GeoIPLookup handles IP to country lookup using MaxMind GeoLite2-Country database.
func NewGeoIPLookup ¶
func NewGeoIPLookup() *GeoIPLookup
NewGeoIPLookup creates a new GeoIP lookup instance.
func (*GeoIPLookup) Close ¶ added in v0.1.0
func (g *GeoIPLookup) Close() error
Close closes the GeoIP database.
func (*GeoIPLookup) Init ¶
func (g *GeoIPLookup) Init(dbPath string) error
Init initializes the GeoIP database from the given path. If path is empty, GeoIP lookups are disabled (graceful degradation). Returns an error if the database cannot be loaded (logs warning instead).
func (*GeoIPLookup) IsEnabled ¶ added in v0.1.0
func (g *GeoIPLookup) IsEnabled() bool
IsEnabled returns whether GeoIP lookups are available.
func (*GeoIPLookup) LookupCountry ¶
func (g *GeoIPLookup) LookupCountry(ip string) string
LookupCountry returns the 2-letter ISO country code for an IP address. Returns empty string if: - GeoIP is not enabled/initialized - IP address is invalid - Country cannot be determined Returns "LOCAL" for private/local IPs.
func (*GeoIPLookup) Reload ¶ added in v0.1.0
func (g *GeoIPLookup) Reload() error
Reload reloads the GeoIP database if it has been updated. Safe to call periodically (e.g., from a cron job).
type HourlyStat ¶
HourlyStat represents hourly aggregated statistics.
type Module ¶
type Module struct {
module.BaseModule
// contains filtered or unexported fields
}
Module implements the internal analytics module.
func (*Module) CreateSessionHash ¶
CreateSessionHash creates a session proxy hash for grouping page views. Similar to visitor hash but with different suffix for distinct identification.
func (*Module) CreateVisitorHash ¶
CreateVisitorHash creates an anonymized visitor fingerprint hash. The hash combines anonymized IP + user agent + date + salt. This allows counting unique visitors per day without tracking across days.
func (*Module) GetRealTimeVisitorCount ¶
GetRealTimeVisitorCount returns the number of unique visitors in the last N minutes.
func (*Module) GetTrackingMiddleware ¶
GetTrackingMiddleware returns the tracking middleware for use in router setup. This should be called after Init() to ensure settings are loaded.
func (*Module) Migrations ¶
Migrations returns database migrations.
func (*Module) RegisterAdminRoutes ¶
RegisterAdminRoutes registers admin routes.
func (*Module) RegisterRoutes ¶
RegisterRoutes registers public routes (none for this module).
func (*Module) ReloadSettings ¶
ReloadSettings reloads settings from the database.
func (*Module) RunAggregationNow ¶
RunAggregationNow runs all aggregation jobs immediately (for testing).
func (*Module) RunFullAggregation ¶ added in v0.3.0
RunFullAggregation aggregates all historical raw data into daily stats. This backfills page_analytics_daily from page_analytics_views for all past dates.
func (*Module) SidebarLabel ¶
SidebarLabel returns the display label for the admin sidebar.
func (*Module) StartAggregator ¶
func (m *Module) StartAggregator()
StartAggregator starts background aggregation jobs.
func (*Module) TemplateFuncs ¶
TemplateFuncs returns template functions provided by the module.
func (*Module) TrackingMiddleware ¶
TrackingMiddleware returns middleware that tracks page views.
func (*Module) TranslationsFS ¶
TranslationsFS returns module translations.
type OverviewStats ¶
type OverviewStats struct {
TotalViews int64
UniqueVisitors int64
BounceRate float64 // percentage
ViewsToday int64
ViewsYesterday int64
TrendPercent float64 // change from yesterday
RealTimeVisitors int // visitors in last 5 minutes
}
OverviewStats contains summary statistics for the dashboard.
type PageView ¶
type PageView struct {
ID int64
VisitorHash string // Anonymized visitor fingerprint (daily rotating)
Path string // URL path (e.g., "/about")
PageID *int64 // FK to pages.id (nullable for non-page routes)
ReferrerDomain string // Extracted referrer domain
CountryCode string // 2-letter ISO country code
Browser string // Browser name (Chrome, Firefox, Safari, etc.)
OS string // Operating system
DeviceType string // desktop, mobile, tablet
Language string // Accept-Language primary language
SessionHash string // Session proxy (IP+UA+date hash)
CreatedAt time.Time // When the view occurred
}
PageView represents a single page view event stored in the database.
type ParsedUA ¶
type ParsedUA struct {
Browser string
OS string
DeviceType string // "desktop", "mobile", "tablet"
}
ParsedUA holds parsed user agent information.
type ReferrerStat ¶
type ReferrerStat struct {
ID int64
Date time.Time
ReferrerDomain string
Views int
UniqueVisitors int
}
ReferrerStat represents daily referrer statistics.
type Settings ¶
type Settings struct {
Enabled bool
RetentionDays int
ExcludePaths []string
CurrentSalt string
SaltCreatedAt time.Time
SaltRotationHours int
}
Settings holds module configuration.
type TechStat ¶
type TechStat struct {
ID int64
Date time.Time
Browser string
OS string
DeviceType string
Views int
}
TechStat represents daily browser/device statistics.
type TimeSeriesPoint ¶
TimeSeriesPoint represents a data point for time series charts.
type TopPage ¶
type TopPage struct {
Path string
PageID *int64
PageTitle string
Views int64
UniqueVisitors int64
BounceRate float64
}
TopPage represents a page in the top pages list.
type TopReferrer ¶
TopReferrer represents a referrer in the top referrers list.