Erlang SDK reference
Read time: 3 minutes
Last edited: Feb 23, 2021
Overview
This topic explains the basics of the LaunchDarkly Erlang server-side SDK and how it works.
To learn more, visit our Erlang SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. Additionally, you can clone and run sample applications using this SDK with Erlang, Elixir, and the Phoenix framework.
Getting started
Follow the steps below to get started using the LaunchDarkly SDK in your Erlang application.
First, you'll need to download the dependency using Rebar.
{deps, [
{ldclient, "1.0.0", {pkg, launchdarkly_server_sdk}}
]}.
And then add it to your app.src
file.
{applications,
[kernel,
stdlib,
ldclient
]},
If you're using Elixir you can download the dependency using Mix.
defp deps do
[
{:ldclient, "~> 1.0.0", hex: :launchdarkly_server_sdk}
]
end
After you install the SDK dependency, create an instance of the SDK.
% This starts an instance with the default options
ldclient:start_instance("YOUR_SDK_KEY")
% You can also start a named instance
ldclient:start_instance("YOUR_SDK_KEY", my_instance)
Now you can check which flag variation a specific user should receive.
Flag = ldclient:variation(<<"YOUR_FLAG_KEY">>, #{key => <<"123">>}, false)
Customizing your client
You can pass other custom parameters when the client starts by using the Options
map parameter:
% Specify options
ldclient:start_instance("YOUR_SDK_KEY", #{stream => false})
% With a custom instance name
ldclient:start_instance("YOUR_SDK_KEY", my_instance, #{stream => false})
The code sample above turns off streaming. The SDK now connects to LaunchDarkly through polling.
Users
Feature flag targeting and rollouts are determined by the user you pass to your variation calls.
Map = #{
key => <<"aa0ceb">>,
secondary => <<"abc">>,
ip => <<"198.51.100.0">>,
country => <<"your-country">>,
email => <<"foo@bar.com">>,
first_name => <<"a">>,
last_name => <<"z">>,
avatar => <<"ratavA">>,
name => <<"foobar">>,
anonymous => false,
<<"custom-key">> => <<"custom-value">>
},
User = ldclient_user:new_from_map(Map)
All of the other attributes, like FirstName
, Email
, and the custom attributes, are optional. The attributes you specify appear on the LaunchDarkly dashboard automatically. You can start making user segments and targeting users with these attributes right away.
In addition to built-in attributes like names and email addresses, you can pass any of your own user data as key-value pairs in the map, like the CustomKey
in the example above. Custom attributes are one of LaunchDarkly's most powerful features. They let you target users according to any data that you want to send, including organizations, groups, and account plans. Anything you pass to us becomes available instantly on our dashboard.
Anonymous users
Key = <<"aa0ceb">>,
Anonymous = true,
Map = #{
key => Key,
anonymous => Anonymous,
},
User = ldclient_user:new_from_map(Map)
You must still generate a unique key for anonymous users. We recommend using Session IDs or UUIDs.
Anonymous users are similar to regular users, but they have the following limitations:
- they don't appear on your Users dashboard in LaunchDarkly,
- they don't appear in search results on your Feature Flags page, and
- you can't search or autocomplete by anonymous user keys.
Private user attributes
You can configure the Erlang SDK to treat some or all user attributes as private user attributes. You can use private user attributes to target users without sending data associated with that user back to LaunchDarkly.
To learn more about private user attributes, read Setting user attributes.
When you create the Options map, use the private_attributes
key to set private user attributes. When you do this, the SDK does not send the user attributes you specify to LaunchDarkly.
ldclient:start_instance("YOUR_SDK_KEY", my_instance, #{private_attributes => [email]})
Variation
The variation
function determines whether a flag is enabled or not for a specific user.
The functions take a flag key, user, default value and an instance tag. The instance tag is optional. The default variation only returns if an error occurs.
For example, if the feature flag key doesn't exist or the user doesn't have a key specified, the user sees the default variation value.
Flag = ldclient:variation(<<"my-bool-key">>, #{key => <<"aa0ceb">>,}, false, my_instance)
VariationDetail
The variation_detail
function is similar to the variation function, but also returns an explanation of the evaluation that you can inspect programatically.
To learn more about this data, read Flag evaluation rules.
Flag = ldclient:variation_detail(<<"my-bool-key">>, #{key => <<"aa0ceb">>}, false)
All flags
The all_flags_state
function captures the state of all feature flag keys as evaluated for a specific user. This includes their values and other metadata.
This method is useful when you're passing feature flags to the frontend. Specifically, you can use it to provide bootstrap flag settings for our JavaScript SDK.
To learn more, read the JavaScript SDK reference.
ldclient:all_flags_state(#{key => <<"aa0ceb">>})
Track
The track
function lets you record actions your users take on your site, so you can record events that take place on your server. In LaunchDarkly, you can tie these events to metrics in experiments.
In this example, we connect a metric to track:
ldclient:track(<<"YOUR-METRIC-KEY">>, #{key => <<"aa0ceb">>}, #{data => <<"example">>})
You can also attach a JSON object containing arbitrary data to your event, or a custom metric value using the track_metric
function.
ldclient:track_metric(<<"YOUR-METRIC-KEY">>, #{key => <<"aa0ceb">>}, #{data => <<"example">>}, 0.5)
Identify
The identify
function creates or updates users on LaunchDarkly, making them available for targeting and autocomplete on the dashboard.
In most cases, you won't need to call identify
. The variation
call automatically creates users on the dashboard for you. identify
is useful if you want to pre-populate your dashboard before you launch any features.
ldclient:identify(#{key => <<"aa0ceb">>})
Offline mode
In some situations, you might want to stop making remote calls to LaunchDarkly and fall back to your feature flags' default values.
For example, if your software is both cloud-hosted and distributed to customers to run on premise, it might make sense to fall back to defaults when the software runs on-premise.
You can do this by setting offline mode in the config map with the offline
key.
ldclient:start_instance("YOUR_SDK_KEY", #{offline => true})
Shutting Down
stop_instance()
, stop_instance(Tag)
, and stop_all_instance()
all safely shut down client instances and releases the resources associated with them.
In most long-running applications, you will not have to call these functions. You can use them to ensure all events have been flushed synchronously before closing your application.
Do not evaluate flags after any of these functions have been initiated.
ldclient:stop_all_instances()
% Stops the default instance
ldclient:stop_instance()
% Stops a named instance
ldclient:stop_instance(my_instance)
Database integrations
The Erlang SDK can use Redis as a persistent store of feature flag configurations.
To learn more, read Using a persistent feature store.