Umami Ruby

A Ruby wrapper for the Umami analytics API.

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

Usage

Configuration

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

For self-hosted Umami instances:

# 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

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

For Umami Cloud:

Umami.configure do |config|
  config.access_token = "your_api_key"
  # No need to specify uri_base for Umami Cloud
end

Using the Client

After configuration, you can use the client to interact with the Umami API:

client = Umami::Client.new

# Get all websites
websites = client.websites

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

# Get website stats
stats = client.website_stats("website_id", { startAt: 1656679719687, endAt: 1656766119687 })

# Verify token
token_info = client.verify_token

Error Handling

The gem defines several custom error classes:

Umami::ConfigurationError: Raised for configuration-related issues.
Umami::AuthenticationError: Raised for authentication-related issues.
Umami::APIError: Raised for API request failures.

Logging

The gem uses a logger that can be configured:

Umami.logger.level = Logger::DEBUG

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec 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.