Ruby SDK Pro

Send events from any Ruby app using a project API key. Pure stdlib, no external dependencies. Works with Rails, Sinatra, Sidekiq workers, scheduled jobs, and anything else that runs Ruby 3.0+.

clamp-sh/analytics-rubyMIT

View source Issues

Paste to your agent

Wire Clamp into a Rails app

Adds the clamp-analytics gem, initializes it on boot, and tracks the project's primary conversion event from the relevant controller or job.

Wire Clamp Analytics into this Ruby app.

Read https://clamp.sh/docs/sdk/ruby.

1. ASK ME for a Clamp project API key (format `sk_proj_...`) and add it to the env as CLAMP_API_KEY. Wait for confirmation. Do not invent a key.
2. Add 'clamp-analytics' to the Gemfile, then run bundle install.
3. Initialize once at boot:
     # config/initializers/clamp.rb (Rails)
     Clamp::Analytics.init(project_id: '<the project id>', api_key: ENV.fetch('CLAMP_API_KEY'))
   For Sinatra: in the configure block. For Sidekiq: in a server middleware that calls init at startup.
4. Track the primary conversion event. For Stripe webhooks: in checkout.session.completed and invoice.paid:
     Clamp::Analytics.track('subscription_started',
       properties: {
         plan: plan,
         total: Clamp::Analytics::Money.new(amount, currency)
       },
       anonymous_id: session.client_reference_id
     )
   Amounts in major units (29.00, not 2900). Currency ISO 4217 uppercase.
5. ASK ME to trigger a test event and confirm it appears at https://clamp.sh/dashboard. If not, surface Rails.logger output and debug with me before claiming success.
6. Stop and report: which controller or job you wired, where CLAMP_API_KEY is read from, and whether the test event landed in the dashboard.

Install

Gemfile

gem "clamp-analytics"

Then:

terminal

bundle install

Ruby 3.0+ supported. The gem uses only the standard library (net/http, json, time, uri).

Use an API key that starts with sk_proj_ from Settings → API Keys. Keys are scoped to one project.

Quick start

config/initializers/clamp.rb

require "clamp_analytics"

Clamp::Analytics.init(
  project_id: "proj_xxx",
  api_key: ENV.fetch("CLAMP_API_KEY")
)

anywhere.rb

Clamp::Analytics.track("signup", properties: { plan: "pro", method: "email" })

Clamp::Analytics.track(
  "subscription_started",
  properties: {
    plan: "pro",
    total: Clamp::Analytics::Money.new(29.00, "USD")
  },
  anonymous_id: "aid_xxx"
)

API

Clamp::Analytics.init(project_id:, api_key:, endpoint: nil)

Initializes the SDK. Call once at app boot. State is held at the module level behind a Mutex, safe across threads.

Clamp::Analytics.track(name, properties: , anonymous_id: nil, timestamp: nil)

Sends a server event. Returns true on success.

name: event name string.
properties: optional hash. Values may be String, Integer, Float, true/false, or Money. Other types raise ArgumentError.
anonymous_id: optional. Links to a browser visitor.
timestamp: optional Time (non-UTC times are normalized to UTC) or ISO 8601 string.

Raises Clamp::Analytics::HTTPError on non-2xx responses, Clamp::Analytics::NotInitializedError if initwasn't called.

Clamp::Analytics::Money

purchase.rb

Clamp::Analytics.track("purchase", properties: {
  plan: "pro",
  total: Clamp::Analytics::Money.new(29.00, "USD"),
  tax: Clamp::Analytics::Money.new(4.35, "USD")
})

amount is in major units (29.00, not 2900). currency is an ISO 4217 code.

Framework integrations

Rails

config/initializers/clamp.rb

require "clamp_analytics"

Clamp::Analytics.init(
  project_id: Rails.application.credentials.clamp[:project_id],
  api_key: Rails.application.credentials.clamp[:api_key]
)

app/controllers/signups_controller.rb

class SignupsController < ApplicationController
  def create
    user = User.create!(signup_params)

    Clamp::Analytics.track("signup",
      properties: { plan: user.plan, method: "email" },
      anonymous_id: cookies[:clamp_aid]
    )

    redirect_to welcome_path
  end
end

Sinatra

app.rb

require "sinatra"
require "clamp_analytics"

configure do
  Clamp::Analytics.init(
    project_id: ENV.fetch("CLAMP_PROJECT_ID"),
    api_key: ENV.fetch("CLAMP_API_KEY")
  )
end

post "/checkout" do
  session = create_stripe_session(params)
  Clamp::Analytics.track("checkout_started",
    properties: { plan: params[:plan] },
    anonymous_id: params[:anon_id]
  )
  json url: session.url
end

Sidekiq

For high-throughput webhook handlers, push the track call to a Sidekiq job so the request returns fast.

app/jobs/report_subscription_started.rb

class ReportSubscriptionStarted
  include Sidekiq::Job

  def perform(plan, amount, currency, anonymous_id)
    Clamp::Analytics.track("subscription_started",
      properties: {
        plan: plan,
        total: Clamp::Analytics::Money.new(amount, currency)
      },
      anonymous_id: anonymous_id
    )
  end
end

Errors and retries

The gem is synchronous and raises on failure. There are no automatic retries. Rescue around calls if you want fire-and-forget:

safe_track.rb

begin
  Clamp::Analytics.track("subscription_started", properties: ...)
rescue Clamp::Analytics::Error => e
  Rails.logger.error("clamp: #{e.message}")
end

Linking browser and server events

Pass the anonymous ID from the browser to your API, then include it in server-side calls. See the linking pattern on the server-side docs page; the same pattern applies in Ruby.