Overview
The Sidecar SDK is used to interact with the Stigg Sidecar Service, which provides low latency entitlement checks, handles caching, and subscribes to real-time entitlement and usage data updates.Learn more about the Stigg Sidecar service.
Since Sidecar SDK version
3.0.0
, the TLS connection method has been deprecated in favor of non-TLS. Please ensure you are running a compatible Sidecar image version 2.494.0
or later. For backwards compatibility details, check the changelog. TLS self-signed certificates will expire on January 26, 2026, so upgrading the Sidecar image is strongly recommended.Installing the SDK
The first step is to install the Stigg SDK as a dependency in your application:Retrieving the server API Key
In the Stigg app, go to Settings -> Account -> Environments. Copy the Server API key of the relevant environment.Initializing the SDK
Development
Import the Stigg SDK and initialize it with your environment API key:For testing & development purposes, Stigg will run the Sidecar service in a child process. The service listens for requests on address
localhost:80
by default.For production, it is highly recommend to do run the Sidecar in a separate container, you can find more info in the Sidecar page.Production
For production use, its recommended to deploy the Sidecar service using the sidecar pattern, or as a standalone service. You set the remote sidecar host and port parameters as part of the SDK initialization:Learn more about running the Sidecar service as separate container.
Running in offline or air-gapped environments
In air-gapped or highly secure environments where the Sidecar service cannot be deployed, you can use the Sidecar SDK in offline mode. This mode enables entitlement evaluation entirely in-memory without connecting to a remote or local Sidecar process. Offline mode is ideal for:- Air-gapped deployments
- Environments with restricted network access
- Testing with predefined entitlement data
The Offline mode is only available in Java SDK (v2.420.0+). This mode supports all entitlement types (boolean, numeric, metered). Usage and event reporting (
reportUsage
, reportEvents
) are disabled in the offline mode.OfflineStiggConfig
, supplying a customer-to-entitlements mapping either programmatically or via a JSON string.
Initializing with programmatic config
You can pass static entitlement data directly as Java objects:Initializing from a JSON string
You can also load entitlements from a JSON string:Checking entitlements
All entitlement methods -getXEntitlement
and getEntitlements
- remain the same:
Getting the entitlement of a customer to a specific feature
Generic entitlement check (recommended)
ThegetEntitlement
method provides a unified way to check any type of feature entitlement. It automatically returns the appropriate entitlement type based on the feature configuration.
The generic
getEntitlement
method is the recommended approach for checking feature entitlements as it provides a unified interface and automatically handles all entitlement types. For metered features, you can also pass a requestedUsage
parameter to proactively check if additional usage would be allowed.Checking the entitlement of a boolean feature
Checking the entitlement of a numeric configuration feature
Checking if a customer has access to a metered feature
Proactively checking if a customer will have access to X units of a metered feature
Getting all of the entitlements for a specific customer
Reporting usage measurements to Stigg
The Stigg SDK allows you to report usage measurements for metered features. The reported usage will be used to track, limit and bill the customer’s usage of metered features. Stigg supports metering of usage from the following data sources:- Calculated usage - usage that has been aggregated and calculated by your application. This type is useful for features, such as: seats.
- Raw events - raw events from your application, which Stigg filters and aggregates aggregate to calculate customer usage. This type is useful for features, such as: monthly active users (MAUs).
Stigg's metering and aggregation capabilities
- Reporting of measurements to Stigg should be done only after the relevant resources have been provisioned in your application.
- To ensure that the provisioned resources are aligned with the measurements that are reported to Stigg, ensure that customers are not allowed to allocate new resources until an acknowledgement about the processed measurement is received from the Stigg backend.
Validating that a measurement was successfully reported to Stigg is also possible in the customer details section of the relevant customer in the Stigg app.
Calculated usage
updateBehavior
parameter:
Raw events
The
dimensions
field support key value pairs, while keys are strictly of type string
values can be string | number | boolean
Access to additional Stigg APIs
The Sidecar SDK exposes a type-safe generated API client that can be used for send requests to the Stigg API:Persistent caching
In order for the cache to survive between restarts or to be shared across multiple instances of the Sidecar service, you can configure the Sidecar to use Redis as a cache provider.Prerequisites
Run a Persistent Cache Service in a separate process.SDK configuration
Benchmarks
Based on internal benchmarks, a single instance of the Sidecar service—connected to a Redis cluster as the cache layer—can handle:- Throughput: A steady rate of 1200 requests per second (RPS).
- Latency: p95 latency under 10ms.
- Deployment model: Designed to run either as a sidecar container alongside your application or as a standalone service.
- CPU and memory: 1 vCPU and 512MB RAM are sufficient to run a single instance.
- CPU usage: Averages around 70%, with a range between 40% and 75% under constant load.
- Memory footprint: Approximately 250MB.
- Scalability: The service is stateless and horizontally scalable.