Java
The official Schematic Java library, supporting Java 8+.
Installation and Setup
- Add the dependency using your build tool of choice:
Using Gradle in build.gradle
:
Using Maven in pom.xml
:
-
Issue an API key for the appropriate environment using the Schematic app.
-
Using this secret key, initialize a client in your application:
Usage
Sending identify events
Create or update users and companies using identify events.
This call is non-blocking and there is no response to check.
Sending track events
Track activity in your application using track events; these events can later be used to produce metrics for targeting.
This call is non-blocking and there is no response to check.
If you want to record large numbers of the same event at once, or perhaps measure usage in terms of a unit like tokens or memory, you can optionally specify a quantity for your event:
Creating and updating companies
Although it is faster to create companies and users via identify events, if you need to handle a response, you can use the companies API to upsert companies. Because you use your own identifiers to identify companies, rather than a Schematic company ID, creating and updating companies are both done via the same upsert operation:
Checking flags
When checking a flag, you’ll provide keys for a company and/or keys for a user. You can also provide no keys at all, in which case you’ll get the default value for the flag.
Webhook Verification
Schematic can send webhooks to notify your application of events. To ensure the security of these webhooks, Schematic signs each request using HMAC-SHA256. The Java SDK provides utility functions to verify these signatures.
Verifying Webhook Signatures
When your application receives a webhook request from Schematic, you should verify its signature to ensure it’s authentic:
Verifying Signatures Manually
If you need to verify a webhook signature outside of the context of a servlet request, you can use the verifySignature
method:
Configuration Options
There are a number of configuration options that can be specified using the builder when instantiating the Schematic client.
Flag Check Options
By default, the client will do some local caching for flag checks. If you would like to change this behavior, you can do so using initialization options to specify the cache providers:
You can also disable local caching entirely; bear in mind that, in this case, every flag check will result in a network request:
You may want to specify default flag values for your application, which will be used if there is a service interruption or if the client is running in offline mode:
Offline Mode
In development or testing environments, you may want to avoid making network requests when checking flags or submitting events. You can run Schematic in offline mode:
When in offline mode:
- Flag checks will return the default value for the flag being checked (false by default, or as specified in flagDefaults)
- Events (identify and track) will be skipped completely
- All other API calls will use a no-op HTTP client that doesn’t make actual network requests, returning empty responses
This is especially useful for development, testing, or when running unit tests that shouldn’t depend on the Schematic API.
Offline mode works well with flag defaults:
Event Buffer
Schematic API uses an Event Buffer to batch Identify and Track requests and avoid multiple API calls. You can set the event buffer flush period:
Exception Handling
When the API returns a non-success status code (4xx or 5xx response), a subclass of SchematicException
will be thrown.
The SDK also supports error handling for first class exceptions with strongly typed body fields.
Retries
The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retriable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).
A request is deemed retriable when any of the following HTTP status codes is returned: