Ruby SDK
Feature flags and "In your code" experiments on your server, decided the same way the browser decides them, and events sent from it. It's one file for Ruby 3.0 or newer, using only the standard library: Rails, Sinatra and any Rack app.
Install
curl -o peekbird.rb https://peekbird.com/sdk/peekbird.rbPut the file in your project and require it. Make one client per process, with a key from Site settings → Server keys:
require_relative "peekbird"
# Once, when your server starts. The key is in Site settings → Server keys.
PEEKBIRD = Peekbird::Client.new(ENV.fetch("PEEKBIRD_KEY"))In Rails, keep the file in vendor/ (Rails doesn't autoload it) and use an initializer:
# config/initializers/peekbird.rb, with the file in vendor/peekbird.rb
require_relative "../../vendor/peekbird"
PEEKBIRD = Peekbird::Client.new(ENV.fetch("PEEKBIRD_KEY"))
PEEKBIRD.ready(timeout: 5) # optional: wait for the flags and experimentsThe client downloads your flags and experiments in a background thread, then decides locally, checks for changes every 30 seconds and sends events every 5. Until the first download, flags are off and experiments answer nil.
Decide
# In a controller or Rack app: reads Peekbird's cookies from the request.
visitor = PEEKBIRD.visitor(request)
if PEEKBIRD.variation("one-page-checkout", visitor) == "one-page"
# Show the new version.
end
visitor.write_cookies(response) # Peekbird's cookies, as the snippet reads themvisitor = PEEKBIRD.visitor(request)
if PEEKBIRD.flag("new-search", visitor)
# The new feature.
endvariation(key, visitor)answers the variation's key, ornilwhen the visitor isn't in the test. It counts them in the test the first time: ask where the variations start to differ.flag(key, visitor)answerstrueorfalse. A flag that doesn't exist is off. Each answer is noted once per visitor, for the Feature flag filter.
Set the cookies
After deciding, visitor.write_cookies(response) adds Peekbird's cookies to a Rails or Rack response, or a Rack headers hash, on Rack 2 and 3: the visitor's ID when the SDK made it, and their variations, so the snippet in the page shows the same ones. Don't use Rails' cookies[...] = or Rack's set_cookie for them: they encode characters the snippet reads as they are. visitor.cookies_to_set has the raw Set-Cookie values if you need them.
Send events
PEEKBIRD.track(visitor, "purchase", revenue: 49.9, currency: "USD", order_id: "ORDER-123")revenue: is an amount of money with its currency:, value: any other amount a goal adds up, and an order with an order_id: counts once. Other keywords go in the event's properties: text, numbers or true/false. PEEKBIRD.identify(visitor, id:, email:, name:) says who the visitor is. In a rake task or a job that ends right away, call PEEKBIRD.flush at the end.
The visitor
PEEKBIRD.visitor(request) takes a Rails request, a Rack::Request (Sinatra's too) or a Rack env. It reads the cookies, User-Agent, Accept-Language, Referer, the page's address, Sec-GPC, and behind Cloudflare CF-IPCountry and CF-Region-Code. Add facts you know, or describe a visitor without a request:
PEEKBIRD.visitor(request, attributes: { plan: current_user.plan })
# A visitor you describe, with your own ID: the same answer on every device.
PEEKBIRD.visitor(id: current_user.id, attributes: { plan: "pro", lifetime_value: 250 }, time_zone: "America/Chicago")Make one visitor per request and use it for every call in it. What else a server knows, and what it can't, is on Server-side SDKs. Time zones work with TZInfo (Rails loads it) or the system's zone files; without either, only UTC and offsets such as +09:00.
Rails
class ApplicationController < ActionController::Base
after_action { @peekbird_visitor&.write_cookies(response) }
helper_method :peekbird_visitor
private
def peekbird_visitor
@peekbird_visitor ||= PEEKBIRD.visitor(request, attributes: { plan: current_user&.plan })
end
end
class CheckoutsController < ApplicationController
def show
render :one_page if PEEKBIRD.variation("one-page-checkout", peekbird_visitor) == "one-page"
end
def create
order = Order.create!(order_params)
PEEKBIRD.track(peekbird_visitor, "purchase", revenue: order.total.to_f, currency: "USD", order_id: order.number)
redirect_to order
end
endIn a view:
<% if PEEKBIRD.flag("new-search", peekbird_visitor) %>
<%= render "new_search" %>
<% end %>Sinatra
require "sinatra"
require_relative "peekbird"
PEEKBIRD = Peekbird::Client.new(ENV.fetch("PEEKBIRD_KEY"))
get "/checkout" do
visitor = PEEKBIRD.visitor(request)
page = PEEKBIRD.variation("one-page-checkout", visitor) == "one-page" ? :checkout_one_page : :checkout
visitor.write_cookies(response)
erb page
endRack
class App
def call(env)
visitor = PEEKBIRD.visitor(env)
body = PEEKBIRD.flag("new-search", visitor) ? "New search" : "Search"
headers = { "content-type" => "text/plain" }
visitor.write_cookies(headers)
[200, headers, [body]]
end
endConsent
Where your site waits for consent (see Consent), the SDK follows the same rule as the snippet. For a visitor who hasn't agreed, it sets no cookies and sends no events, and experiments answer nil. Flags are still answered, since deciding one stores and sends nothing. Tell it what your own banner knows with consent: true.
Options
PEEKBIRD = Peekbird::Client.new(
ENV.fetch("PEEKBIRD_KEY"),
refresh_interval: 30, # seconds between checks for changed flags and experiments; nil: load once
flush_interval: 5, # seconds between sends of waiting events
timeout: 5, # seconds a request to Peekbird may take
on_error: ->(error) { Rails.logger.warn(error.message) }, # never raised
)flushsends what's waiting now;closestops the background thread and sends it. Ruby sends what's left when it exits.- Puma in cluster mode, Unicorn and Passenger fork workers: each starts its own background thread on its first call, with nothing to set up.
- Nothing the SDK does raises into your code. Without
on_error:, each message is printed once as a warning.
