Use cases for SDK wrappers

Overview

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 context objects across SDKs

More use cases are explained in Use cases for SDK wrappers.

Prerequisites

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 Variation and Track.

Concepts

Before you read this guide, you should understand the following concepts:

SDK wrappers

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.

Understanding why to wrap an SDK

SDK wrappers help enforce consistent SDK usage. By implementing a wrapper, you can mandate consistency across your SDK configuration, context 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.

Using SDK wrappers in different design patterns

You can implement SDK wrappers in different design patterns depending on the architecture of your codebase and the outcomes you want to achieve.

Bridge patterns

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

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.

Mid-session update policies (client-side)

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.

Encapsulated SDKs

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 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 context 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.

Use cases for SDK wrappers

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.

Migrating from an existing flag system

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.

Acting as a mock for tests

When you run automated tests, the wrapper can use a fixed or pre-defined state instead of building a real LDClient.

Automatically providing context

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. To learn more about setting up different context kinds, read Context kinds.

This implementation is especially useful for API communication within microservices, where the microservice client can automatically encode context attributes into request headers.

Enforcing correct definition of the context

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 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 context attributes as private.

This is very useful for maintaining end user privacy and consistency across your codebase.

Improving observability

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.

Providing a single source of fallback flag values

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 false to 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.

Acting as an evaluation error handler

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.

Combining the SDK & API client behind one interface

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.

Conclusion

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.