Server-side SDKs
Decide feature flags and A/B tests on your own server, and send events from it: Node.js, PHP, Python, Ruby and Go, plus an HTTP API for anything else. A visitor gets the same answer on your server and in the page.
| SDK | Runs on | Install |
|---|---|---|
| Node.js | Node.js 18+, Next.js, Vercel and Cloudflare edge, Deno, Bun | npm install https://peekbird.com/sdk/peekbird-node.tgz |
| PHP | PHP 8.1+: plain PHP, Laravel, Symfony, WordPress | curl -o Peekbird.php https://peekbird.com/sdk/Peekbird.php |
| Python | Python 3.9+: Django, Flask, FastAPI | pip install https://peekbird.com/sdk/peekbird-python.tar.gz |
| Ruby | Ruby 3.0+: Rails, Sinatra, any Rack app | curl -o peekbird.rb https://peekbird.com/sdk/peekbird.rb |
| Go | Go 1.21+: net/http, chi, gin, echo | curl --create-dirs -o peekbird/peekbird.go https://peekbird.com/sdk/peekbird.go |
| Anything else | Any language that speaks HTTP | The server API |
For now, each SDK installs from peekbird.com. None needs other packages.
What they're for
- Feature flags: turn a feature on for a share of visitors or an audience, and off again at once, with no deploy.
- "In your code" experiments (see Experiments): your code asks which variation a visitor gets, on the server or in the page, and does what it says. Prices, search results, a checkout flow, emails: anything code decides. There's no flicker, since the page is sent as it should look.
- Events from your server: an order confirmed by your payment provider, a sign-up, a cancellation. They count for goals like the page's.
Set up
- In your site's Site settings, under Server keys, make a key. It's shown once: put it in your server's environment, never in a page.
- Install the SDK, and make one client when your server starts:
npm install https://peekbird.com/sdk/peekbird-node.tgz
import { Peekbird } from '@peekbird/node';
// Once, when your server starts. The key is in Site settings → Server keys.
const peekbird = new Peekbird({ key: process.env.PEEKBIRD_KEY });
await peekbird.ready();curl -o Peekbird.php https://peekbird.com/sdk/Peekbird.php
require_once __DIR__ . '/Peekbird.php';
// The key is in Site settings → Server keys.
$peekbird = new \Peekbird\Peekbird(getenv('PEEKBIRD_KEY'));pip install https://peekbird.com/sdk/peekbird-python.tar.gz
import os
from peekbird import Peekbird
# Once, when your server starts. The key is in Site settings → Server keys.
peekbird = Peekbird(os.environ["PEEKBIRD_KEY"])curl -o peekbird.rb https://peekbird.com/sdk/peekbird.rb
require_relative "peekbird"
# Once, when your server starts. The key is in Site settings → Server keys.
PEEKBIRD = Peekbird::Client.new(ENV.fetch("PEEKBIRD_KEY"))curl --create-dirs -o peekbird/peekbird.go https://peekbird.com/sdk/peekbird.go
// import "example.com/yourapp/peekbird": your module's path, then /peekbird.
// Once, when your server starts. The key is in Site settings → Server keys.
pb := peekbird.New(os.Getenv("PEEKBIRD_KEY"))
defer pb.Close()The client downloads your site's flags and "In your code" experiments and decides locally, with no request per decision. It checks for changes every 30 seconds, so switching a flag off reaches your servers within about half a minute. Events wait in memory and go in batches every few seconds. PHP, whose requests don't share memory, keeps the flags in a temporary file for 30 seconds and sends a request's events when it ends.
Decide
window.peekbird = window.peekbird || [];
peekbird.push(['variation', 'one-page-checkout', function (variation) {
if (variation === 'one-page') {
// Show the new version.
}
}]);// In a request handler (Express, Next.js, Fastify, …): reads and sets Peekbird's cookies.
const visitor = peekbird.visitor(req, res);
if (peekbird.variation('one-page-checkout', visitor) === 'one-page') {
// Show the new version.
}// visitor() and variation() set Peekbird's cookies: call them before any output.
$visitor = $peekbird->visitor();
if ($peekbird->variation('one-page-checkout', $visitor) === 'one-page') {
// Show the new version.
}# In a view: your framework's cookies and headers.
visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
if peekbird.variation("one-page-checkout", visitor) == "one-page":
... # Show the new version.
# Then, on your response:
for name, value, attrs in visitor.cookies_to_set:
response.set_cookie(name, value, **attrs)# 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// In a handler: reads and sets Peekbird's cookies.
visitor := pb.Visitor(w, r)
if pb.Variation("one-page-checkout", visitor) == "one-page" {
// Show the new version.
}curl https://app.peekbird.com/api/v1/decide \
-H "Authorization: Bearer $PEEKBIRD_KEY" \
-H "Content-Type: application/json" \
-d '{"visitor": {"id": "VISITOR_ID"}, "experiments": ["one-page-checkout"]}'
# → {"experiments": {"one-page-checkout": "one-page"}, ...}- Asking for a variation counts the visitor in the test, once: ask where the variations start to differ, not on every page.
- Tests in a mutually exclusive group never share a visitor here either: a visitor in one gets nothing from the others.
- Each flag's answer is noted once per visitor, for the Feature flag filter in Recordings, Analytics, Heatmaps and Funnels.
- A visitor who isn't in the test (their audience, the traffic share, or a test that isn't running) gets nothing: null, None, nil or "". Show them the original.
- Before the first download, and if Peekbird can't be reached, flags are off and tests answer nothing. Your site keeps working; nothing ever throws into your code.
window.peekbird = window.peekbird || [];
peekbird.push(['flag', 'new-search', function (on) {
if (on) {
// The new feature.
}
}]);const visitor = peekbird.visitor(req, res);
if (peekbird.flag('new-search', visitor)) {
// The new feature.
}$visitor = $peekbird->visitor();
if ($peekbird->flag('new-search', $visitor)) {
// The new feature.
}visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
if peekbird.flag("new-search", visitor):
... # The new feature.visitor = PEEKBIRD.visitor(request)
if PEEKBIRD.flag("new-search", visitor)
# The new feature.
endvisitor := pb.Visitor(w, r)
if pb.Flag("new-search", visitor) {
// The new feature.
}curl https://app.peekbird.com/api/v1/decide \
-H "Authorization: Bearer $PEEKBIRD_KEY" \
-H "Content-Type: application/json" \
-d '{"visitor": {"id": "VISITOR_ID"}, "flags": ["new-search"]}'
# → {"flags": {"new-search": true}, ...}The same answer everywhere
Every SDK and the snippet decide with the same rule: the same hash of the same visitor ID and the test's own seed. So they agree without asking each other, and a test the server decides and one the page decides split visitors the same way.
- The visitor's ID is Peekbird's
_peekbird_uidcookie when the request has one, so your server and the snippet are the same visitor. Without it, the SDK makes an ID and sets the cookie. - For someone signed in, you can use your own ID instead: then every device they use gets the same answer.
- A visitor's variation is kept in the
_peekbird_expcookie, as the snippet keeps it, so changing a test's split later doesn't move them.
The snippet beside them
Keep the snippet on your pages: it records the analytics, recordings, heatmaps and goals your tests are measured with. When every test is decided on your server, nothing has to change the page before it shows, so load it with async and the page never waits for it. That makes testing on your server the fastest kind there is: the page arrives already showing its variation.
<script async src="https://cdn.peekbird.com/s/YOUR_SITE_KEY.js"></script>- Keep it without
asyncif you also run split-URL tests, or tests from the visual editor or with code in the page: they have to act before the page shows, or visitors see the original flash first. - Page code that asks the snippet for a flag or a variation while the page loads should use the queued form, which waits for it (see JavaScript API).
What a server knows about a visitor
Audiences work on a server with what it knows:
- From the request: the page's address (query parameters, UTM tags), the user agent (device, browser, operating system), the language and the referrer. Behind Cloudflare, the country too.
- From the snippet's cookies, when the request carries them: visit number, days since the first visit, pages viewed this visit, the visit's traffic source and UTM tags, location, and attributes set with
peekbird.push(['set', …]). - From you: attributes for "Custom attribute" conditions (a plan, a lifetime value), a country, region or city, and a time zone for day and hour conditions (UTC otherwise).
Screen width and JavaScript conditions need a browser: on a server they never match, so leave them out of audiences your server decides. A first visit with no cookies counts as a new visitor.
Send events
peekbird.track(visitor, 'purchase', { revenue: 49.9, currency: 'USD', orderId: 'ORDER-123' });$peekbird->track($visitor, 'purchase', ['revenue' => 49.9, 'currency' => 'USD', 'orderId' => 'ORDER-123']);peekbird.track(visitor, "purchase", revenue=49.9, currency="USD", order_id="ORDER-123")PEEKBIRD.track(visitor, "purchase", revenue: 49.9, currency: "USD", order_id: "ORDER-123")pb.Track(visitor, "purchase", peekbird.Properties{Revenue: 49.9, Currency: "USD", OrderID: "ORDER-123"})curl https://app.peekbird.com/api/v1/events \
-H "Authorization: Bearer $PEEKBIRD_KEY" \
-H "Content-Type: application/json" \
-d '{"events": [{"type": "event", "visitorId": "VISITOR_ID", "name": "purchase", "revenue": 49.9, "currency": "USD", "orderId": "ORDER-123"}]}'Events from servers count like the page's: orders once by their ID, goals by event name (see Goals and audiences). identify says who the visitor is, as in the page (see Who the visitor is).
Previews and QA
Preview links work on servers too. With ?peekbird_force=one-page-checkout:one-page or ?peekbird_qa=1 on the page's address, or the cookies the snippet keeps for them, the SDKs force that variation or run tests in QA, and those visits count as QA traffic, never in results. See QA and preview.
Keys
- Make one key per place that uses it (Production, Staging), so you can revoke one without touching the others.
- Revoking a key stops it within a minute. Peekbird keeps only a fingerprint of each key, never the key itself.
- Only editors and owners see and make keys. A key reads the site's flags and "In your code" experiments and sends its events, nothing else.
Limits and the HTTP details are in Server API. Native iOS and Android SDKs aren't available.
