Use cases for SDK wrappers
Read time: 6 minutes
Last edited: Jul 25, 2022
This guide explains how to use an SDK wrapper to facilitate interactions between LaunchDarkly SDKs and your codebase. Your application source code can use a wrapper instead of directly interfacing with our SDKs' APIs.
This can be useful for a number of reasons. For example, an SDK wrapper lets you:
- Use consistent default values in variation methods for the engineers working with the SDK
- Implement specific business logic relating to feature flag evaluation
- Consistently define user objects across SDKs
More use cases are explained in Use cases for SDK wrappers.
To complete this guide, you must have the following prerequisites:
- The ability to create flags in your LaunchDarkly account.
- Familiarity with the LaunchDarkly SDK you use.
- Familiarity with the LaunchDarkly SDK API, such as
Before you read this guide, you should understand the following concepts:
An SDK wrapper is a data type or struct that acts as a facade around the LaunchDarkly SDK. SDK wrappers can simplify your workflow by making an SDK easier to use or more accessible to your codebase. For example, you can write an SDK wrapper that lets you call
FlagRollout instead of
BoolVariation. If you're working with a complicated SDK, you can write a wrapper that calls the SDK with some pre-defined limitations to simplify the call.
SDK wrappers help enforce consistent SDK usage. By implementing a wrapper, you can mandate consistency across your SDK configuration, user object configuration, and default flag values.
If you need to instantiate multiple SDK instances, and you are using a "shared services" or "one project per product line" model, wrapping an SDK helps you manage the complexity of having multiple SDK instances by abstracting them.
Furthermore, wrapping an SDK lets you enforce consistent usage among developers, including for configuration, user object creation, and default flag values.
You can implement SDK wrappers in different design patterns depending on the architecture of your codebase and the outcomes you want to achieve.
If you need to use a singleton, read the documentation for the SDK you use to learn how to create and use singletons. The API and SDK documentation all explain which SDKs support singleton usage and how to implement them.
Bridge patterns allow your codebase to feature flag through a custom interface rather than through the SDK's interface. Bridge patterns can be useful when you're transitioning from a legacy flag system.
Composite patterns simplify code that needs to evaluate flags across multiple projects or environments. You can give the SDK wrapper multiple SDK keys on initialization, so it can instantiate and cache an
LDClient instance for each key. The app then requests an
LDClient for a specific environment when needed, and the wrapper provides it from the instance cache.
For example, you can use an SDK wrapper as a single-instance facade for multiple client instances. Instead of handling the app-specific
LDClient instance, the wrapper does the flag evaluation itself, without being told which environment to use. The wrapper receives the flag key, and then picks the appropriate
LDClient for the evaluation.
Composite patterns are useful when you need to access multiple projects or environments from a single app. Several of the LaunchDarkly mobile SDKs, including Android, iOS, and React Native, provide this feature by default without needing a wrapper, but you must use a wrapper to add this behavior to other SDKs.
When you set a wrapper to run mid-session updates, the wrapper can change an end user's experience of your app while they use it. When a flag updates in the middle of an app session, the wrapper can trigger a state update, and change the end user's experience without requiring a refresh.
When you encapsulate an SDK, the wrapper reads app configuration and knows how to construct
LDClient based on the app. Multiple SDKs use the same wrapper library. This makes it easier to do mass reconfiguration of the SDKs, because updates you make to the wrapper affect all the SDKs inside it.
You can also encapsulate an
LDClient instance with a user context so you can pass them as a single object. This is the existing pattern provided by our client-side SDKs. It’s also useful for server-side SDKs in apps that have to evaluate multiple flags for the same user as part of a request or session. In this use case, the object also acts as a single request/session context, which is useful for observability purposes.
You can use an SDK wrapper to add or extend existing functionality to LaunchDarkly SDKs. Here are some examples of what you can use SDK wrappers to do.
You can use an SDK wrapper to facilitate migration from an existing flag system. The wrapper hides clients for both LaunchDarkly and the existing system. The wrapper enables flag evaluation without the code needing to know which of its configured environments contains the flag. This means that flags can be moved without requiring code changes.
On flag evaluation, the wrapper chooses the appropriate client for the flag being evaluated. During the migration process, some flags may exist in both systems, in which case it helps to have a dedicated flag which specifies which system should be prioritized for evaluation.
To learn more, read Migrating your existing feature flag solution to LaunchDarkly.
When you run automated tests, the wrapper can use a fixed or pre-defined state instead of building a real
You can use an SDK wrapper to automatically add environmental context, such as operating system (OS), browser, or app version. A wrapper can also read user context from environment variables.
This implementation is especially useful for API communication within microservices, where the microservice client can automatically encode user attributes into request headers. The LaunchDarkly mobile SDKs already implement some of this behavior by automatically providing the OS and the device's custom attributes.
An SDK wrapper can ensure consistency by enforcing the ways that different code and apps use the same attributes. For example, a wrapper can fix the casing or spelling of attribute names, which is especially useful when the same flag is in use across different environments.
A wrapper can also spot and prevent common problems in how user attributes are filled, scan attribute values for common personally identifiable information (PII) formats such as phone numbers and social security numbers, and automatically mark certain user attributes as private.
This is very useful for maintaining user privacy and consistency across your codebase.
An SDK wrapper can update your observability contexts whenever feature flags are evaluated. For example, you can append the evaluated flag variations and the evaluation reason alongside any other metrics to be sent to your observability tool.
An SDK wrapper can provide a variation call that doesn’t ask for a fallback value, because this is configured for each flag in a centralized place. This ensures fallback values are consistent across your codebase, lets you update fallback values with a network-accessible resource, and, for client-side apps, makes it easier to switch the fallback from
true as soon as possible after a feature launches.
This is helpful if you evaluate specific flags in multiple places in your codebase and is in line with the Don't Repeat Yourself (DRY) principle of software development. To learn more, read Don't repeat yourself.
An SDK wrapper catches evaluation failures and uses the
EvaluationReason to handle them appropriately. This is useful when specific failure types should raise an exception instead of only serving the fallback value.
For example, an SDK wrapper can use the
EvaluationReason to handle situations where the code needs to be sure that a
false value is coming from the flag evaluation, and not a fallback value served due to lack of connection to or data from LaunchDarkly. Another example is that rules that use Big Segments may also evaluate as
true even if the Big Segment data is unavailable. The only way to diagnose this problem is by checking the
Using an SDK wrapper to combine an SDK and an API client lets you read, write, and evaluate flags from one API. This is useful for code that needs to evaluate flags as well as modify them.
LaunchDarkly SDKs let you evaluate feature flags and record experimentation events, but do not manage what feature flags do (for example, changing targeting rules) or perform general-purpose actions on your LaunchDarkly account.
The API client libraries, however, provide native interfaces for interacting with LaunchDarkly’s REST API. You can use the REST API to manage feature flags and perform general purpose actions for a customer’s LaunchDarkly account.
To learn more about the API, visit the API client libraries.
When you combine the SDK and API in a wrapper, the wrapper uses the LaunchDarkly REST API to fetch metadata about each flag, such as its title, description, tags, and custom attributes. You can use the metadata to describe policies, fallback values, and other information the wrapper needs. This gives you more power over flag and SDK behavior without needing additional user interface (UI) or services.
In this guide, we discussed what SDK wrappers are, different implementation patterns for creating them, and common use cases you can use to get more value out of LaunchDarkly.
Your 14-day trial begins as soon as you sign up. Learn to use LaunchDarkly with the app's built-in tutorial. You'll discover how easy it is to manage the whole feature lifecycle from concept to launch to control.
Want to try it out? Start a trial.