Aptabase Ruby SDK

Ruby and Rails SDK for Aptabase - open source, privacy-first analytics for mobile, desktop and web applications.

Status: 0.x - the API is stable and verified against the live Aptabase ingestion API, but minor releases may still include breaking changes until 1.0.

Features

• 🧵 Non-blocking - track queues in memory; a background thread does the sending
• 🔒 Privacy-first - no personal data collection, no device identifiers
• 🔄 Auto-batching - events are batched (max 25) and flushed every 10 seconds
• ♻️ Resilient - failed batches are re-queued and retried; tracking never raises on network errors
• ⚡ Zero dependencies - stdlib only
• 🛤️ Rails-friendly - install generator, Rails.logger integration, fork-safe under Puma cluster mode, flushes on exit

Requirements

• Ruby 3.1+
• Rails 7.1+ (optional - the SDK works in any Ruby program)

Installation

Add to your Gemfile:

gem "aptabase-ruby"

Or install directly:

gem install aptabase-ruby

Quick Start

require "aptabase"

Aptabase.init("A-EU-1234567890") # your app key

# Track a simple event
Aptabase.track("app_started")

# Track an event with properties
Aptabase.track("user_action", {
  "action" => "button_click",
  "button_id" => "login",
  "screen" => "home"
})

# Events are flushed automatically (and on process exit),
# but you can force it:
Aptabase.flush

Rails

Add the gem, then generate the initializer:

rails generate aptabase:install

This creates config/initializers/aptabase.rb, which reads the app key from Rails.application.credentials.dig(:aptabase, :app_key) or ENV["APTABASE_APP_KEY"].

Then call Aptabase.track anywhere - controllers, jobs, models:

class OrdersController < ApplicationController
  def create
    # ...
    Aptabase.track("order_created", { "total_cents" => order.total_cents })
  end
end

The SDK logs through Rails.logger by default, restarts its background thread automatically in forked Puma/Unicorn workers, and flushes pending events when the process exits.

See samples/rails-app for a runnable single-file example.

Configuration

Aptabase.init(
  "A-EU-1234567890",          # Your Aptabase app key
  app_version: "1.2.3",       # Your app's version, shown in the dashboard
  is_debug: false,            # Debug events are kept separate in Aptabase
  max_batch_size: 25,         # Max events per request (hard max 25)
  flush_interval: 10.0,       # Auto-flush interval in seconds
  timeout: 30.0,              # HTTP timeout in seconds
  logger: Logger.new($stderr) # Where SDK warnings/debug logs go
)

App Key Format

Your app key determines the server region:

Key prefix	Region
A-EU-*	European servers
A-US-*	US servers
A-SH-*	Self-hosted - requires the base_url: option

Get your app key from the Aptabase dashboard.

# Self-hosted instance
Aptabase.init("A-SH-1234567890", base_url: "https://analytics.example.com")

Instance API

For multiple apps or explicit lifecycle control, use Aptabase::Client directly:

client = Aptabase::Client.new("A-EU-1234567890", app_version: "1.0.0")
client.track("event")
client.flush          # synchronous send
client.pending_count  # events queued, not yet delivered
client.stop           # flushes remaining events

# Block form - stop/flush guaranteed on exit
Aptabase::Client.start("A-EU-1234567890") do |client|
  client.track("event")
end

Sessions

Events are grouped into sessions automatically. A session id is reused until one hour of inactivity, then rotated - the same semantics and id format as the official Aptabase SDKs, so dashboards behave identically.

Error Handling

Network failures never raise from track - failed batches are logged, re-queued and retried on the next flush. Programmer errors do raise:

Error	Raised when
Aptabase::ConfigurationError	bad app key or invalid options
Aptabase::ValidationError	bad event name or props
Aptabase::NetworkError	internal transport failures (#status_code)

All inherit from Aptabase::Error.

Samples

• Simple script - plain Ruby, no framework
• Rails app - single-file Rails app via bundler/inline

Development

bundle install
bundle exec rspec    # run tests
bundle exec rubocop  # lint

# run the suite against a specific Rails version
BUNDLE_GEMFILE=gemfiles/rails_80.gemfile bundle install
BUNDLE_GEMFILE=gemfiles/rails_80.gemfile bundle exec rspec

Contributing

Bug reports and pull requests are welcome at tiny-cloud-ventures/aptabase-ruby.

License

MIT

This is a community SDK, ported from the official aptabase-python SDK.