Skip to content
Peekbird

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.rb

Put 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 experiments

The 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 them
visitor = PEEKBIRD.visitor(request)
if PEEKBIRD.flag("new-search", visitor)
  # The new feature.
end
  • variation(key, visitor) answers the variation's key, or nil when 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) answers true or false. 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
end

In 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
end

Rack

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
end

Consent

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
)
  • flush sends what's waiting now; close stops 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.

See what your visitors see.

Start free in a few minutes: one snippet, every feature. Move to a bigger plan when you need more tracked visits.