Erlang SDK reference

Read time: 3 minutes

Last edited: Mar 10, 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.

Use a single instance

While the Erlang SDK supports starting multiple instances, most use cases only need a single instance. Consider using multiple instances only if you need to simultaneously access more than one environment. Do not start an instance every time you need to make a variation or other SDK call.

% 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)

The user key is mandatory.

The most important attribute in the example above is the user key. The user key should be unique to each user. In the example above, we used the binary `aa0ceb`. You can use a primary key, an email address, or a hash, as long as the same user always has the same key. We recommend using a hash if possible.

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.

The SDK always sends the user key.

The user key is not optional. You cannot set it as a private user attribute.

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 front end. 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.