Python 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 needs Python 3.9 or newer and nothing else, and works with Django, Flask, FastAPI and any other framework.
Install
pip install https://peekbird.com/sdk/peekbird-python.tar.gzThen make one client per process, when your server starts, with a key from Site settings → Server keys:
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"])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 None. A script that decides straight away can wait:
peekbird.ready(timeout=5) # True once the flags and experiments are loaded.Decide
# 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)visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
if peekbird.flag("new-search", visitor):
... # The new feature.variation(key, visitor)answers the variation's key, orNonewhen 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, set visitor.cookies_to_set on your response: the visitor's ID when the SDK made it, and their variations, so the snippet in the page shows the same ones. Each is a (name, value, attrs) tuple whose attrs fit Django's, Flask's and Starlette's set_cookie:
for name, value, attrs in visitor.cookies_to_set:
response.set_cookie(name, value, **attrs)For a raw WSGI or ASGI response, visitor.set_cookie_headers has them as ready Set-Cookie values. The cookies are Secure unless the page's address is plain http: behind a proxy that ends HTTPS, make sure your framework sees the https address (Django's SECURE_PROXY_SSL_HEADER, Werkzeug's ProxyFix, uvicorn's --proxy-headers).
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_id is counted once. Other keyword arguments go in the event's properties: text, numbers or true/false. peekbird.identify(visitor, id=..., email=..., name=...) says who the visitor is.
To count an order that a webhook confirms later, keep the visitor's ID with the order:
# At checkout, keep visitor.id with the order. When the payment webhook confirms it:
visitor = peekbird.visitor(order.peekbird_visitor_id)
peekbird.track(visitor, "purchase", revenue=order.total, currency=order.currency, order_id=order.number)The visitor
peekbird.visitor(cookies=..., headers=..., url=...) reads a request: cookies as a dict or the Cookie header, headers as any mapping or a WSGI environ, and the page's full address. It reads User-Agent, Accept-Language, Referer, Sec-GPC, and behind Cloudflare CF-IPCountry and CF-Region-Code. Or describe a visitor you know:
visitor = peekbird.visitor(
"user-42", # your own ID for someone signed in: the same answer on every device
attributes={"plan": "pro", "ltv": 250},
country="US",
region_code="TX",
time_zone="America/Chicago",
)Facts you pass win over the headers. What else a server knows, and what it can't, is on Server-side SDKs. On Windows, install the tzdata package for time zones; without it every time zone counts as UTC.
Django
# views.py
from django.shortcuts import render
from .peekbird_client import peekbird # Peekbird(os.environ["PEEKBIRD_KEY"]), made once
def checkout(request):
visitor = peekbird.visitor(
cookies=request.COOKIES,
headers=request.headers,
url=request.build_absolute_uri(),
)
one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
response = render(request, "checkout.html", {"one_page": one_page})
for name, value, attrs in visitor.cookies_to_set:
response.set_cookie(name, value, **attrs)
return responseFlask
@app.route("/checkout")
def checkout():
visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=request.url)
one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
response = make_response(render_template("checkout.html", one_page=one_page))
for name, value, attrs in visitor.cookies_to_set:
response.set_cookie(name, value, **attrs)
return responseFastAPI
@app.get("/checkout")
def checkout(request: Request, response: Response):
visitor = peekbird.visitor(cookies=request.cookies, headers=request.headers, url=str(request.url))
one_page = peekbird.variation("one-page-checkout", visitor) == "one-page"
for name, value, attrs in visitor.cookies_to_set:
response.set_cookie(name, value, **attrs)
return {"one_page": one_page}Deciding and tracking don't touch the network, so they're fine in async def endpoints too. When an endpoint returns its own response object, set the cookies on that one.
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 None. Flags are still answered, since deciding one stores and sends nothing. Tell it what your own banner knows with consent=True.
Options
peekbird = Peekbird(
os.environ["PEEKBIRD_KEY"],
refresh_interval=30, # seconds between checks for changed flags and experiments; 0: load once
flush_interval=5, # seconds between sends of waiting events
timeout=5, # seconds a request to Peekbird may take
on_error=log_it, # a function that gets a PeekbirdError: never raised
)flush()sends what's waiting now;close()stops the background thread and sends it. The client also works as a context manager.- In AWS Lambda or Google Cloud Functions, call
peekbird.flush()before the function returns: the process may be frozen afterwards. - One client serves every thread. With servers that fork after loading your app (gunicorn
--preload, uWSGI), each worker starts its own background thread. - Nothing the SDK does raises into your code. Without
on_error, each kind of problem is logged once on thepeekbirdlogger.
