SDKs
Installation
To install an SDK, see one of the language quickstarts.
Auto-generated, type-safe client
SDKs come with a CLI tool to auto-generate a client so you can access your flags with end-to-end type-safety. This ensures typos in flag names or incorrectly passed targeting attributes can be caught at build-time rather than runtime. It also improves the developer experience with code completion, "find all references" and type-safe flag clean up.
Initialization
During initialization, SDKs fetch your flag logic from Hypertune Edge.
You can optionally specify an initialization query to:
Select which flags to fetch
Provide some targeting attributes upfront so that any flag logic that depends on those attributes can be partially reduced on the edge
This is useful for:
Performance
You can limit which flags are fetched to reduce the network payload size
You can partially reduce flag logic on the edge to:
Reduce the network payload size
Reduce the logic that needs to be locally evaluated by the SDK
Security
You can eliminate sensitive logic, e.g. a list of user IDs, on the edge so it doesn't get leaked to publicly accessible clients, e.g. in the browser
Build-time fallback snapshot of flag logic
You can embed a fallback snapshot of your flag logic in the generated client.
The SDK will locally, reliably and instantly initialize from the snapshot first, before fetching the latest flag logic from Hypertune Edge. So even in the unlikely event that Hypertune Edge is unreachable, SDKs will still successfully initialize from the snapshot.
This is useful on the frontend as you can use your flags in the first app render without any page load delay, UI flicker or layout shift.
It's also useful for running an SDK in local-only, offline mode for unit tests.
The snapshot can be kept fresh by setting up a webhook to automatically regenerate it on every Hypertune commit, then committing the result to your own repo.
Hard-coded fallbacks
Whenever you evaluate a flag, you pass a hard-coded fallback value.
If Hypertune Edge is unreachable and there's no build-time logic fallback, or there's an error evaluating the flag, you'll get this hard-coded fallback value instead.
This ensures that in the worst-case scenario, your app still works properly.
Local-only, offline mode
You can disable server initialization and use a build-time fallback snapshot of flag logic to use SDKs in local-only, offline mode. This is useful for running tests.
Bootstrap from your own server
You can "bootstrap" an SDK from your own server. If you use an SDK on your backend, you can pass the state of the SDK to the client, e.g. the browser, and then instantly initialize the SDK on the client with this state.
This is particularly useful for server-side rendering, e.g. with Next.js, as you can initialize the SDK and use your flags in the first app render on the client without any page load delay, UI flicker or layout shift.
Wait for server initialization
SDKs expose methods to wait for and check for server initialization. This is useful if you want to guarantee flag values are fresh.
Provide targeting attributes
You can define targeting attributes at the:
rootlevelindividual flag level
And provide them during:
SDK initialization
local flag evaluation
a mix of both
Typically, you'll provide targeting attributes when locally evaluating the root flag, passing it the context argument you defined in your schema. You'll get back the Root SDK node which will have type-safe methods to evaluate all your individual flags.
You can also provide flag-specific targeting attributes when evaluating individual flags.
Local, synchronous flag evaluation
SDKs evaluate flags locally, synchronously, in-memory with no network latency. This includes flag logic that contains A/B tests, machine learning loops and event logging.
So you can use an SDK on the backend to evaluate flags, including A/B tests, for different users without adding latency to every request.
And you can use an SDK on the frontend to evaluate flags, including A/B tests, without blocking renders.
Rust core
Hypertune SDKs are built with a fast, memory-safe Rust core that locally reduces and evaluates your flag logic.
Sending logs
SDKs send logs to Hypertune Edge in the background. This allows you to:
See how often different parts of your flag logic are called, e.g. to see how often different targeting rules are evaluated and passed in realtime
Log events and exposures for your A/B tests and machine learning loops
See any SDK errors from the Hypertune UI
You can also manually trigger and wait for logs to be flushed.
Getting updates
SDKs listen for updates to your flag logic in the background. When you save and activate a new commit from the Hypertune UI, the SDK will fetch your new flag logic and use it on the next evaluation.
You can also manually trigger and wait for a re-initialization from the server.
And you can add and remove listeners to be notified of updates, e.g. to trigger a re-render on the frontend after an update.
Serverless environments
Hypertune SDKs have been uniquely architected to work optimally in serverless environments, e.g. Vercel deployments, Cloudflare Workers, AWS Lambdas, etc.
Vercel Edge Config
If you deploy on Vercel, you can initialize the SDK with near-zero latency in Vercel's edge environment when you set up our Vercel Edge Config integration.
Custom logging
By default, SDKs output info and error logs to the console. But you can provide a custom logging callback to capture and forward logs elsewhere, e.g. to your monitoring infrastructure.
Pin to a schema version
You can pin SDKs to a major version of your schema so that if you make a breaking change that bumps the major version, e.g. removing a flag, it will continue to initialize from the latest commit for the old schema version, until you re-run code generation and update the pinned version.
Shutting down
You can shut down an SDK to cleanly stop all its background processes and terminate all its connections. This is useful when running tests.
Last updated