Haskell SDK reference

Overview

This reference guide documents all of the methods available in our Haskell SDK, and explains in detail how these methods work. If you want to dig even deeper, our SDKs are open source. To learn more, visit our Haskell SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. Additionally you can clone and run a sample application using this SDK.

Getting started

Follow the steps below to get started using the LaunchDarkly SDK in your Haskell application.

The root module of the SDK LaunchDarkly.Server re-exports the entire project. That's all that you need to start.

1import LaunchDarkly.Server
COPY

After you import and install the SDK, create a single shared instance of Client.

Specify your SDK key here to authorize your application to connect to LaunchDarkly for a particular environment.

1client :: IO Client
2client = makeClient $ makeConfig "YOUR_SDK_KEY"
COPY

Using client, you can check which variation a particular user should receive for a given feature flag.

1boolVariation client "YOUR_FLAG_KEY" (makeUser "abc") False
COPY

Customizing your client

You can also pass other custom parameters to the client with the configuration object:

1{-# LANGUAGE OverloadedStrings #-}
2
3import LaunchDarkly.Server.Config
4
5import Data.Function ((&))
6
7config :: Config
8config = (makeConfig "YOUR_SDK_KEY")
9    & configSetEventsCapacity 1000
10    & configSetFlushIntervalSeconds 30
COPY

In the example above, we've customized the event queue capacity and flush interval parameters. To learn more about the specific user properties that are available in this SDK, read the SDK's API docs.

Users

Feature flag targeting and rollouts are all determined by the user you pass to your variation calls.

1{-# LANGUAGE OverloadedStrings #-}
2
3import LaunchDarkly.Server.User
4
5import Data.Function ((&))
6
7user :: User
8user = (makeUser "aa0ceb")
9    & setFirstName "Ernestina"
10    & setLastName "Evans"
11    & setEmail "ernestina@example.com"
COPY

The most important attribute in the example above is the user key. The user key is mandatory.

In the example above, we used the hash "aa0ceb".

The user key should be unique to each user. 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 custom attributes, like the groups attribute 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.

Private user attributes

Optionally, you can configure the Haskell SDK to treat some or all user attributes as private user attributes. You can use private user attributes for targeting purposes without sending data about the user associated with them back to LaunchDarkly.

To learn more about private user attributes, read Setting user attributes.

When you create the Config object, use configSetAllAttributesPrivate to set all user attributes as private. When you do this, all user attributes (except the key) are removed before the user is sent to LaunchDarkly.

1config' = configSetAllAttributesPrivate True config
COPY

When you create the Config object, you can list specific private attributes with configSetPrivateAttributeNames. If any user has a custom or built-in attribute named in this list, it is removed before the user is sent to LaunchDarkly.

1import Data.Set (fromList)
2
3config' = configSetPrivateAttributeNames (fromList ["email"]) config
COPY

You can also define private attribute names on a per-user basis.

For example:

1import Data.Set (fromList)
2
3user' = userSetPrivateAttributeNames (fromList ["email"]) user
COPY

Aliased users

There are situations in which multiple LaunchDarkly users can represent one person. For example, this can happen when a person initially logs into an application. The person might be represented by an anonymous user before they log in, and a different user after they log in. In that case, that one person would be identified by two different users as denoted by different user keys.

The SDK can associate these two LaunchDarkly users by sending an alias event. You can manually tell the SDK to send an alias event with the alias function.

1alias client newUser previousUser
COPY

Variation

The variation family of functions determine whether a flag is enabled or not for a specific user.

1myBoolVariation <- boolVariation client user "YOUR_FEATURE_KEY" False
COPY

The functions take a Client, User, feature flag key, and a default value.

The default value 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 default value is returned.

VariationDetail

The variationDetail functions are similar to the variation functions, but they also return an explanation of the evaluation that is programmatically inspectable.

To learn more about the "reason" data, read Evaluation reasons.

1details :: IO (EvaluationDetail Bool)
2details = boolVariationDetail client user "YOUR_FEATURE_KEY" False
COPY

For specific information on the EvaluationDetail structure, inspect the LaunchDarkly.Server.Details module.

All flags

The allFlags function captures the state of all feature flag keys as evaluated for a specific user. This includes their values, as well as other metadata.

This method is useful when you're passing feature flags to your front end. Specifically, you can use it to provide bootstrap flag settings for our JavaScript SDK.

To learn more, read the JavaScript SDK reference.

1state = allFlags client user
COPY

Anonymous users

You can also distinguish logged-in users from anonymous users in the SDK.

1user` = userSetAnonymous True user
COPY

You still must generate a unique key for anonymous users. Session IDs or UUIDs work best for this.

Anonymous users work just like regular users, except that they won't appear on your Users page in LaunchDarkly. You also can't search for anonymous users on your Features page, and you can't search or autocomplete by anonymous user keys. This is actually a good thing, because it keeps anonymous users from polluting your Users page!

Flush

The LaunchDarkly SDK keeps an internal event buffer for analytics events. These events are flushed periodically in a background thread. In some situations, you may want to manually call flush to process events immediately.

For example, if you're testing the SDK in a simulator, you may want to flush example events.

1flushEvents client
COPY

This function will not block, but instead initiate a flush operation in the background. The flush interval is configurable. If you need to change the interval, you can do so via the configuration.

Track

The track function allows you to record actions your users take on your site. This lets you record events that take place on your server. In LaunchDarkly, you can tie these events to metrics in experiments.

For example:

1track client user "your-metric-key" Nothing Nothing
COPY

You can also attach a JSON object containing arbitrary data to your event, or a custom metric value.

Identify

In most cases, you won't need to call identify. The variation call will automatically create users on the dashboard for you. identify is useful if you want to pre-populate your dashboard before launching any features.

1identify client user
COPY

Offline mode

In some situations, you might want to stop making remote calls to LaunchDarkly and fall back to default values for your feature flags. You can do this by setting offline mode in the config object with configSetOffline.

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 running on premise.

1config' = configSetOffline True config
COPY

Shutting down

close safely shuts down the client instance and releases all resources associated with the client.

In most long-running applications, you should not have to call close, but you can use it to ensure all events have been flushed synchronously before closing your application.

You should not evaluate flags after close has been initiated.

1close client
COPY