• Home
  • Integrations
  • SDKs
  • Guides
  • API docs
No results for ""
EXPAND ALL

EDIT ON GITHUB

Using LaunchDarkly without a supported SDK

Read time: 8 minutes
Last edited: May 20, 2022

Overview

This guide explains your options for working with LaunchDarkly without a supported SDK for your tech stack.

LaunchDarkly supports a variety of SDKs for client-side and server-side development. To review the complete list, read Available SDKs. If the tech stack your organization uses is not in this list, you have several options.

Your options include:

This guide describes each option, why you might use it, how to employ it, and some of its advantages and disadvantages.

Prerequisites

To complete this guide, you must have the following prerequisites:

  • A tech stack that is not compatible with our available SDKs. If we have an SDK for your language or platform, you should use that instead of any of the strategies described in this guide.

    A note about supported SDKs

    In some cases, a supported SDK exists for your technology, but isn't specifically built for your technology. For example, we have a JavaScript SDK and SDKs for a few common JavaScript frameworks. But we don't have specific SDKs for every JavaScript framework.

    If you are using a framework for which we don't yet have a specific SDK, then using the existing supported SDK for your underlying technology should be the first option you consider.

  • An understanding of the differences between client-side and server-side SDKs. The SDK types have different security considerations as well as some behavioral and architectural differences. To learn more, read Client-side and server-side SDKs.

  • Familiarity with making REST requests. Several of the options expose SDK functionality through REST endpoints. If you choose one of these options, you should be comfortable making REST requests from within your application.

  • A basic understanding of the Relay Proxy, and why it might or might not be a good fit for your organization. One of the options involves polling against the Relay Proxy. If you are interested in this option, you should evaluate whether using the Relay Proxy makes sense for you. To learn more, read The Relay Proxy.

Using the Relay Proxy and polling against it

If your tech stack is not compatible with our available SDKs, one option is to use the Relay Proxy and poll against it.

Understanding the Relay Proxy option

The Relay Proxy is a small Go application that connects to the LaunchDarkly streaming API and proxies that connection to clients within an organization's network. It lets multiple servers connect to a local stream instead of making a large number of outbound connections to LaunchDarkly's streaming service. Adding the Relay Proxy to your LaunchDarkly configuration introduces architectural complexity, so it's not for every organization.

If you want to evaluate feature flags without an SDK, the Relay Proxy provides endpoints for evaluating all feature flags for a given user, and you can use these instead.

The Relay Proxy endpoints for evaluating feature flags for a given user are equivalent to the polling endpoints for client-side or mobile SDKs, but can be used whether you are looking for a server-side or client-side SDK.

The endpoints require a base64-encoded user in the request endpoint in order to return feature flag names and the resulting variants for that user. The endpoints use the SDK key as a credential. Remember that the SDK key should be kept secret. To learn more, read Keys.

Implementing the Relay Proxy option

If you choose this option, the first step is to set up the Relay Proxy. To learn how, read Using the Relay Proxy.

To evaluate all flag values for a given user, you have two options:

  • You can make a GET request to your Relay Proxy at the /sdk/eval/users/{user} endpoint, where {user} is the base64-encoded JSON object for the user key.
  • You can make a REPORT request to your Relay Proxy at the /sdk/eval/users endpoint, and include the user key in a JSON object in the request body.

In both cases, you must pass an Authorization header with your SDK key as part of the request. For the REPORT request, you also need a Content-Type header. You might choose to use a REPORT request over a GET request so that the user details are in the request body, where it is less likely that they will be accessible to monitoring and logging tools.

Here's how:

curl -X GET https://your-relay-proxy.com:8080/sdk/eval/users/eyJrZXkiOiAiYTAwY2ViIn0= \
-H "Authorization: YOUR_SDK_KEY"

In the example,

  • https://your-relay-proxy.com:8080 is the local URI and port for your Relay Proxy. Depending on your configuration, your address may be different.
  • eyJrZXkiOiAiYTAwY2ViIn0= is the base64-encoded JSON object for the user key, {"key": "a00ceb"}.

To evaluate all flag values for a given user and also receive additional metadata, such as the evaluation reason, you also have two options:

  • You can make a GET request to the /sdk/evalx/users/{user} endpoint, where {user} is the base64-encoded JSON object for the user key.
  • You can make a REPORT request to the /sdk/evalx/user endpoint and include the user key in a JSON object in the request body.

Here's how:

curl -X GET https://your-relay-proxy.com:8080/sdk/evalx/users/eyJrZXkiOiAiYTAwY2ViIn0= \
-H "Authorization: YOUR_SDK_KEY"

As in the previous example,

  • https://your-relay-proxy.com:8080 is the local URI and port for your Relay Proxy. Depending on your configuration, your address may be different.
  • eyJrZXkiOiAiYTAwY2ViIn0= is the base64-encoded JSON object for the user key, {"key": "a00ceb"}.

To learn more, read Special flag evaluation endpoints in the Relay Proxy GitHub documentation.

Evaluating the Relay Proxy option

Using the Relay Proxy and polling against its endpoints is our recommended choice for production use if there is not an officially supported SDK for your technology. Using the provided endpoints means you don't have to write your own SDK or SDK wrapper, which can save significant time and resources both for startup and for maintenance.

However, using the Relay Proxy comes with its own benefits and drawbacks. If you are not already using the Relay Proxy, then setting up and configuring the Relay Proxy just so you can poll against it means additional infrastructure to maintain as part of your application. To learn more, read Deciding whether to use the Relay Proxy. Additionally, polling against the Relay Proxy will result in much more traffic to your Relay Proxy than there would be with typical usage through one of our supported SDKs. To learn more, read Scaling guidelines.

Using the SDK microservice

This option is unsupported

LaunchDarkly does not provide support for this option. We do provide some resources and guidance, described below.

You should consider carefully whether using an unsupported option is appropriate for your organization.

Another option if there is not a supported SDK for your tech stack is to use the SDK microservice.

Understanding the SDK microservice option

The SDK microservice is a LaunchDarkly Labs project. It is a wrapper application around the Go SDK, and exposes the functionality of the Go server-side SDK over HTTP.

For performance reasons, you should run the SDK microservice on a local network.

Implementing the SDK microservice option

If you choose this option, you can download the SDK microservice from its GitHub repository.

Building and configuring the SDK microservice



To build the SDK microservice, use:

go build .

This produces the executable sdk-microservice.

You can manage the SDK microservice with environment variables. You must set the environment variable SDK_KEY to your LaunchDarkly project's SDK key.

To learn more, read Building and Specifying a configuration in the project's Readme.

Features of the SDK microservice



To evaluate a flag for a given user, make a POST request to the /feature/{key}/eval endpoint, where {key} is the feature flag key. In the body of the request, include the user object and the default value for the flag.

Here's how:

curl -X POST your-local-server/feature/example-flag-key/eval \
-H 'Content-Type: application/json' \
-d '{ "user": user, "defaultValue": false }'

The SDK microservice is a wrapper around the Go SDK, so it includes several additional features available in that SDK. The following table summarizes the features and how to learn more about them.

FeatureDescriptionSDK microservice API documentationAdditional feature information
Evaluating flagsEvaluate a flag for a given userPOST /feature/key/evalEvaluating flags
Flushing eventsSend all pending analytics events to LaunchDarklyPOST /flushFlushing events
Getting all flagsReturn the state of all feature flags targeted to a userPOST /allFlagsGetting all flags
Identifying usersSubmit a user for LaunchDarkly to recordPOST /identifyIdentifying and changing users
Sending custom eventsSubmit an event for LaunchDarkly to trackPOST /trackSending custom events
User configurationConfigure user objects to return specific data to LaunchDarklyUser typeUser configuration

Evaluating the SDK microservice option

Using the SDK microservice option can be a good choice if you need quick access to a wrapper that exposes some functionality from an existing SDK.

We designed the SDK microservice to run on a local network, so your application structure should support that use. This recommendation is based on performance implications. Because the flag evaluation happens over the network, in the POST request, there is some latency cost when compared with using a supported SDK. Running over a local network minimizes this latency cost.

The primary drawback to the SDK microservice is that it is part of LaunchDarkly Labs, and therefore unsupported. We do not have plans to expand or support it.

Writing your own SDK wrapper

This option is unsupported

LaunchDarkly does not provide support for this option. We do provide some resources and guidance, described below.

You should consider carefully whether using an unsupported option is appropriate for your organization.

An SDK wrapper facilitates interactions between your codebase and the corresponding LaunchDarkly SDK. SDK wrappers can simplify your workflow by making an SDK easier to use or more accessible to your codebase. To learn more about SDK wrappers, read Use cases for SDK wrappers.

If LaunchDarkly does not support an SDK for your tech stack, you can write your own SDK wrapper. You might choose this option if there is an interoperability layer between your preferred language and one of our supported languages. You can write a wrapper around the supported SDK using your preferred language.

This is a common pattern, and one that we at LaunchDarkly have used ourselves, for both client-side and server-side SDKs. For example, our React Native SDK is implemented as a wrapper around our Android SDK and iOS SDK. Our Lua SDK is implemented as a thin Lua wrapper on top of our server-side C/C++ SDK.

One benefit of writing your own SDK wrapper is that writing a wrapper is likely to be simpler and faster than writing your own SDK because your wrapper will delegate to the underlying SDK for most functionality. And while your wrapper won't be officially supported, the underlying SDK is.

Writing your own SDK

This option is unsupported

LaunchDarkly does not provide support for this option. We do provide some resources and guidance, described below.

You should consider carefully whether using an unsupported option is appropriate for your organization.

If LaunchDarkly does not support your preferred language, you can also choose to write your own SDK for it. This might be the right option for you if don't want to use the Relay Proxy and you also don't want to rely on the unsupported SDK microservice.

We provide guidance on writing your own SDK in the Contributor's guide. This document includes implementation details on the main components to a LaunchDarkly SDK implementation, including receiving feature flag updates, evaluating feature flags, and recording analytics events. It also covers some best practices and reviews a few common mistakes we've observed. Additionally, all of our existing SDKs are open source, so you can choose one as a reference implementation for your own work.

One benefit of writing your own SDK is that it's entirely under your control. It's also likely the fastest option if your tech stack is particularly unique. However, you do have to build and maintain it yourself, and there may be a bit of a learning curve to get started.

Requesting support for a tech stack

If you don't have interest in or capacity for writing your own SDK or wrapper, using the unsupported SDK microservice, or using the Relay Proxy, then you can request support for a new SDK directly from LaunchDarkly.

To request support for a new SDK, contact Support or your LaunchDarkly account representative.

Depending on overall interest for your requested technology, we may decide to write a new SDK. We may also write a wrapper, if there is a reliable interoperability layer between your language and one of our supported languages.

Making a request is easy, and is one way that LaunchDarkly engineering and product managers stay informed about what technologies our customers are most interested in. However, making a request does not guarantee that we'll create a new SDK for your preferred language, or that we'll create it as quickly as you might prefer.

Conclusion

In this guide, you learned about several options for working with LaunchDarkly without a supported SDK for your tech stack, including why you might choose each option, and some of the advantages and disadvantages of each.

Want to know more? Start a trial.

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.