SDK overview

Traffical SDKs resolve parameters locally inside your application. The SDK downloads a config bundle, evaluates everything in-process, and never blocks your code on a network call.

​

How the SDKs work

1. Fetch the bundle. On startup the SDK fetches the config bundle for your (project, environment) pair. The bundle is a single JSON document containing every parameter, layer, and policy.
2. Resolve locally. When you call getParams (or decide), the SDK computes the user’s bucket from their context, evaluates targeting conditions, and returns the resolved values. Sub-millisecond, no network call.
3. Track events in the background. Exposure and decision events are emitted automatically. Track events you emit explicitly are batched and shipped without blocking the calling code.
4. Refresh automatically. The SDK periodically re-fetches the bundle (default: every 60s). ETag caching means unchanged bundles return 304 Not Modified and cost almost nothing.

​

Graceful degradation

If the bundle hasn’t loaded yet — or if Traffical is unreachable entirely — the SDK returns the defaults you passed in code. Your app keeps working. Traffical can only raise the ceiling, never lower the floor.

​

Evaluation modes

Most SDKs support two evaluation modes: You usually want bundle. Use server when caching a full bundle isn’t reasonable (very limited memory, very rare resolutions) or for per-entity adaptive policies that need the freshest possible weights. See how it works for details.

​

Available SDKs

All SDKs share a common core that implements bundle parsing, bucket hashing, condition evaluation, and resolution — @traffical/core for the TypeScript SDKs, mirrored by the PHP and Swift engines against the same language-agnostic spec. Whichever language or framework you use, the same parameter resolves to the same allocation for the same user.

​

Picking an SDK

• Node.js / Bun backend → @traffical/node. Server runtime, in-memory bundle, sub-ms resolution.
• PHP backend (Laravel, Symfony, plain PHP-FPM) → traffical/sdk. Local resolution, PSR-first, events flushed after the response.
• Python backend (Django, FastAPI, Flask, Celery) → traffical. Sync + asyncio clients, fork-safe local resolution.
• React single-page app or RSC → @traffical/react. Provider + useTraffical hook.
• SvelteKit or Svelte 5 → @traffical/svelte. SSR-friendly with loadTrafficalBundle().
• Plain browser app (Vue, no framework, vanilla) → @traffical/js-client. Direct API.
• Native iOS / macOS / tvOS / watchOS (Swift) → Traffical. SwiftPM, Keychain stable ID, offline baked bundle.
• Mobile (iOS / Android via React Native) → @traffical/react-native.
• Already standardized on OpenFeature → @traffical/openfeature-server / @traffical/openfeature-web. Keep your call sites, swap the provider.

You can mix server and client SDKs in the same app. A common pattern is to resolve on the server for the initial render (no flash of original content) and let the client SDK handle interactive updates. See SSR patterns.

​

Source code

The TypeScript SDK packages live in a public repository at github.com/traffical/js-sdk, the PHP SDK at github.com/traffical/php-sdk, the Python SDK at github.com/traffical/python-sdk, and the Swift SDK at github.com/traffical/ios-sdk. All are MIT-licensed and gated on a shared, language-agnostic conformance spec so bucketing is identical across languages. The @traffical/cli lives in a separate public repository.

​

Next steps