📊 `umami-ruby` – Ruby client for the Umami Analytics API

[!TIP] 🚀 Ship your next Rails app 10x faster! I've built RailsFast, a production-ready Rails boilerplate template that comes with everything you need to launch a software business in days, not weeks. Go check it out!

umami-ruby is a comprehensive Ruby wrapper for the Umami Analytics API. Works with both Umami Cloud and self-hosted instances.

Installation

Add this line to your application's Gemfile:

gem 'umami-ruby'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install umami-ruby

Documentation

Full API documentation is available online or can be generated using YARD:

yard doc
yard server

Configuration

You can put this config in a handy location within your Rails project, like config/initializers/umami.rb

For Umami Cloud

Umami.configure do |config|
  config.access_token = "your_api_key"
  # No need to specify uri_base - automatically uses https://api.umami.is
end

For Self-Hosted Umami Instances

# With an access token
Umami.configure do |config|
  config.uri_base = "https://your-umami-instance.com"
  config.access_token = "your_access_token"
end

# Or with username and password
Umami.configure do |config|
  config.uri_base = "https://your-umami-instance.com"
  config.credentials = {
    username: "your_username",
    password: "your_password"
  }
end

Configuration Options

Option	Description	Default
`access_token`	API key for Umami Cloud or access token for self-hosted	`nil`
`uri_base`	Base URL for self-hosted instances	Auto-detected
`credentials`	Hash with `:username` and `:password` for self-hosted	`nil`
`request_timeout`	Request timeout in seconds	`120`

# Example with custom timeout
Umami.configure do |config|
  config.access_token = "your_api_key"
  config.request_timeout = 60  # 60 seconds
end

Usage

Basic Usage

client = Umami::Client.new

# Get current user info
me = client.me

# Get all websites
websites = client.websites

# Get a specific website
website = client.website("website_id")

# Verify token
token_info = client.verify_token

Website Statistics

# Get website stats for a time range (timestamps in milliseconds)
stats = client.website_stats("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687
})

# Get active visitors (last 5 minutes)
active = client.website_active_visitors("website_id")

# Get pageviews with time grouping
pageviews = client.website_pageviews("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687,
  unit: "day",
  timezone: "America/Los_Angeles"
})

# Get metrics by type
metrics = client.website_metrics("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687,
  type: "browser"  # or: path, referrer, os, device, country, etc.
})

# Get realtime stats (last 30 minutes)
realtime = client.realtime("website_id")

Sending Events

Send custom events to Umami for tracking. This is useful for server-side event tracking.

client = Umami::Client.new

# Send a basic event
client.send_event({
  website: "your-website-id",
  url: "/checkout",
  hostname: "example.com",
  name: "purchase_completed"
})

# Send an event with custom data
client.send_event({
  website: "your-website-id",
  url: "/checkout",
  hostname: "example.com",
  name: "purchase_completed",
  language: "en-US",
  screen: "1920x1080",
  title: "Checkout - Example Store",
  data: {
    order_id: "12345",
    total: 99.99,
    currency: "USD"
  }
})

# Send with a custom User-Agent (optional)
client.send_event(payload, user_agent: "MyApp/1.0")

Important notes about send_event:

No authentication token is sent (not required by the API)
A User-Agent header is automatically included (required by Umami)
For Umami Cloud, requests go to https://cloud.umami.is/api/send (different from other API calls)
For self-hosted, requests go to your configured uri_base

Sessions

# Get sessions within a time range
sessions = client.website_sessions("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687,
  page: 1,
  pageSize: 20
})

# Get session statistics
stats = client.website_sessions_stats("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687
})

# Get individual session details
session = client.website_session("website_id", "session_id")

# Get session activity
activity = client.website_session_activity("website_id", "session_id", {
  startAt: 1656679719687,
  endAt: 1656766119687
})

Events Data

# Get paginated event list with search
events = client.website_events_list("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687,
  search: "click",
  page: 1,
  pageSize: 20
})

# Get event data aggregations
event_data = client.website_event_data_events("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687
})

# Get event statistics
stats = client.website_event_data_stats("website_id", {
  startAt: 1656679719687,
  endAt: 1656766119687
})

Reports

# List reports (optionally filter by website and/or type)
all_reports = client.reports
website_reports = client.reports(websiteId: "website_id")
funnel_reports = client.reports(websiteId: "website_id", type: "funnel")

# Create a report
report = client.create_report({
  websiteId: "website_id",
  type: "funnel",
  name: "Checkout Funnel",
  parameters: {
    startDate: "2024-01-01T00:00:00Z",
    endDate: "2024-01-31T23:59:59Z"
  }
})

# Run specialized reports
funnel = client.report_funnel({
  websiteId: "website_id",
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-01-31T23:59:59Z",
  steps: [
    { type: "path", value: "/" },
    { type: "path", value: "/checkout" },
    { type: "path", value: "/thank-you" }
  ],
  window: 7
})

retention = client.report_retention({
  websiteId: "website_id",
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-01-31T23:59:59Z",
  timezone: "America/Los_Angeles"
})

# Available report types: attribution, breakdown, funnel, goal, journey, retention, revenue, utm

Report types: | Type | Description | |------|-------------| | attribution | Marketing channel attribution analysis | | breakdown | Multi-dimensional data segmentation | | funnel | Conversion funnel tracking | | goal | Goal performance metrics | | journey | User navigation path analysis | | retention | Return visitor analysis | | revenue | Revenue tracking and analysis | | utm | UTM campaign parameter breakdown |

User & Team Management

# Get current user info
me = client.me
my_teams = client.my_teams(page: 1, pageSize: 10)
my_websites = client.my_websites(includeTeams: true)

# Team management
teams = client.teams
team = client.team("team_id")
client.create_team("My Team")
client.add_team_user("team_id", "user_id", "team-member")

# User management (admin only, self-hosted)
users = client.admin_users
client.create_user("username", "password", "user")

Website Management

# Create a website
website = client.create_website({
  name: "My Website",
  domain: "example.com",
  teamId: "optional-team-id"
})

# Update a website
client.update_website("website_id", {
  name: "Updated Name",
  shareId: "public-share-id"
})

# Reset website data
client.reset_website("website_id")

# Delete a website
client.delete_website("website_id")

Available Methods

Authentication

verify_token - Verify the current authentication token

Me (Current User)

me - Get current user information
my_teams(params) - Get user's teams (supports pagination)
my_websites(params) - Get user's websites

Admin (Self-hosted only)

admin_users(params) - List all users
admin_websites(params) - List all websites
admin_teams(params) - List all teams

Users

create_user(username, password, role, id:) - Create a user
user(user_id) - Get user by ID
update_user(user_id, params) - Update user
delete_user(user_id) - Delete user
user_websites(user_id, params) - Get user's websites
user_teams(user_id, params) - Get user's teams

Teams

teams(params) - List all teams
create_team(name) - Create a team
join_team(access_code) - Join a team
team(team_id) - Get team by ID
update_team(team_id, params) - Update team
delete_team(team_id) - Delete team
team_users(team_id, params) - List team members
add_team_user(team_id, user_id, role) - Add user to team
team_user(team_id, user_id) - Get team member
update_team_user(team_id, user_id, role) - Update member role
delete_team_user(team_id, user_id) - Remove user from team
team_websites(team_id, params) - List team websites

Websites

websites(params) - List all websites
create_website(params) - Create a website
website(website_id) - Get website by ID
update_website(website_id, params) - Update website
delete_website(website_id) - Delete website
reset_website(website_id) - Reset website data

Website Statistics

website_stats(website_id, params) - Get statistics
website_active_visitors(website_id) - Get active visitors
website_pageviews(website_id, params) - Get pageviews
website_events(website_id, params) - Get events (time-series)
website_events_series(website_id, params) - Get events series
website_metrics(website_id, params) - Get metrics
website_metrics_expanded(website_id, params) - Get expanded metrics

Sessions

website_sessions(website_id, params) - List sessions
website_sessions_stats(website_id, params) - Get session stats
website_sessions_weekly(website_id, params) - Get weekly breakdown
website_session(website_id, session_id) - Get session details
website_session_activity(website_id, session_id, params) - Get activity
website_session_properties(website_id, session_id) - Get properties
website_session_data_properties(website_id, params) - Get data properties
website_session_data_values(website_id, params) - Get data values

Events

website_events_list(website_id, params) - List events (paginated)
website_event_data(website_id, event_id) - Get event data
website_event_data_events(website_id, params) - Get event aggregations
website_event_data_fields(website_id, params) - Get event fields
website_event_data_properties(website_id, params) - Get event properties
website_event_data_values(website_id, params) - Get event values
website_event_data_stats(website_id, params) - Get event statistics

Realtime

realtime(website_id) - Get realtime stats (last 30 minutes)

Pixels

pixels(params) - List all pixels
pixel(pixel_id) - Get pixel by ID
update_pixel(pixel_id, params) - Update pixel
delete_pixel(pixel_id) - Delete pixel

Reports

reports(params) - List all reports (filter by websiteId, type)
create_report(params) - Create a report
report(report_id) - Get report by ID
update_report(report_id, params) - Update report
delete_report(report_id) - Delete report
report_attribution(params) - Run attribution report
report_breakdown(params) - Run breakdown report
report_funnel(params) - Run funnel report
report_goals(params) - Run goals report
report_journey(params) - Run journey report
report_retention(params) - Run retention report
report_revenue(params) - Run revenue report
report_utm(params) - Run UTM report

Sending Events

send_event(payload, user_agent:) - Send tracking event

Error Handling

The gem defines several custom error classes:

begin
  client.website("non-existent-id")
rescue Umami::NotFoundError => e
  puts "Website not found: #{e.message}"
rescue Umami::ClientError => e
  puts "Client error: #{e.message}"
rescue Umami::ServerError => e
  puts "Server error: #{e.message}"
rescue Umami::AuthenticationError => e
  puts "Authentication failed: #{e.message}"
rescue Umami::ConfigurationError => e
  puts "Configuration error: #{e.message}"
rescue Umami::APIError => e
  puts "API error: #{e.message}"
end

Error class hierarchy:

Umami::Error - Base error class
- Umami::ConfigurationError - Configuration issues
- Umami::AuthenticationError - Authentication failures
- Umami::APIError - API request failures
- Umami::NotFoundError - Resource not found (404)
- Umami::ClientError - Client errors (4xx)
- Umami::ServerError - Server errors (5xx)

Logging

The gem uses a logger that can be configured:

# Set log level
Umami.logger.level = Logger::DEBUG

# Use a custom logger
Umami.logger = Rails.logger

Development

After checking out the repo, run bin/setup to install dependencies. Then, run bundle exec rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/rameerez/umami-ruby. Our code of conduct is: just be nice and make your mom proud of what you do and post online.

License

The gem is available as open source under the terms of the MIT License.

📊 umami-ruby – Ruby client for the Umami Analytics API

Installation

Documentation

Configuration

For Umami Cloud

For Self-Hosted Umami Instances

Configuration Options

Usage

Basic Usage

Website Statistics

Sending Events

Sessions

Events Data

Reports

User & Team Management

Website Management

Available Methods

Authentication

Me (Current User)

Admin (Self-hosted only)

Users

Teams

Websites

Website Statistics

Sessions

Events

Realtime

Links

Pixels

Reports

Sending Events

Error Handling

Logging

Development

Contributing

License

📊 `umami-ruby` – Ruby client for the Umami Analytics API