• SDKS
No results for ""


Lua SDK reference

Read time: 4 minutes
Last edited: May 14, 2021

This reference guide documents basic usage of our Lua server-side SDK, and explains in detail how its functions work. Our SDKs are open source. To learn more, read Lua SDK GitHub repository. The online API docs contain the programmatic definitions of every type and method. In addition to that, you can clone and run a sample application using this SDK. We provide documentation for running the SDK in NGINX, and also HAProxy.

Getting started

Building on top of our Getting Started guide, follow these steps to get started using the LaunchDarkly SDK in your Lua application.

The Lua server-side SDK is implemented using a foreign function interface that calls the C/C++ server-side SDK. You will need the C/C++ server-side SDK dynamic library to be installed somewhere accessible by the linker.

To learn more, read C/C++ SDK reference (server-side).

To get started, include the library:

1local ld = require("launchdarkly_server_sdk")

Once the SDK is installed and imported, you'll want to create a single, shared instance of the client. Specify your SDK key here so that your application will be authorized to connect to LaunchDarkly and for your application and environment.

LDClient should be a singleton

It's important to make this a singleton. The client instance maintains internal state that allows us to serve feature flags without making any remote requests. Be sure that you're not instantiating a new client with every request.

Calling clientInit initiates a remote call to the LaunchDarkly service to fetch feature flags. This call blocks up to the time defined by maxwaitmilliseconds. If you request a feature flag before the client has completed initialization, you receive the default flag value.

1local config = {
2 key = YOUR_SDK_KEY
5local client = ld.clientInit(config, 1000)

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

1if client:boolVariation(user, YOUR_FEATURE_KEY, false) then
2 print "feature is enabled"
4 print "feature is disabled"

Customizing your client

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

1local config = {
2 key = YOUR_SDK_KEY,
3 eventsCapacity = 1000,
4 eventsFlushInterval = 30000
7local client = ld.clientInit(config, 1000)

Here, we've customized the event queue capacity and flush interval parameters. Note that you should finish setting up your configuration object before you call clientInit.

To learn more about configuration options, read the API docs.


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

1local user = ld.makeUser({
2 key = "aa0ceb",
3 firstName = "Ernestina",
4 lastName = "Evans",
5 email = "ernestina@example.com",
6 custom = {
7 groups = { "Google", "Microsoft" }
8 }

Let's walk through this snippet. The most important attribute is the user key. In this case we've used the hash "aa0ceb". The user key is the only mandatory user attribute. The key should also uniquely identify 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 will automatically appear on our dashboard, meaning that you can start segmenting and targeting users with these attributes.

In addition to built-in attributes like names and email addresses, you can pass us any of your own user data by passing custom attributes, like the groups attribute in the example above.

Custom attributes are one of the most powerful features of LaunchDarkly. They let you target users according to any data that you want to send to us, including organizations, groups, andaccount plans. Anything you pass to us becomes available instantly on our dashboard.

To learn more about configuration options, read the API docs.

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

1client:alias(newUser, previousUser)


The variation family of functions determine whether a flag is enabled or not for a specific user. In lua, there is a variation function for each type (e.g. boolVariation, stringVariation, etc).

1local value = client:boolVariation(user, "YOUR_FEATURE_KEY", false)

The default value will only be returned if an error is encountered. For example, the default value returns if the feature flag key doesn't exist or the user doesn't have a key specified.

To learn more about configuration options, read the API docs.

Evaluation details

By using the *Detail family of variation calls you can programmatically inspect the reason for a particular evaluation.

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

1local details = client:boolVariationDetail(client, user, "your.feature.key", false);
3/* inspect details here */
4if details.reason == "FLAG_NOT_FOUND" then

To learn more about configuration options, read the API docs.

All flags

User Creation

Unlike variation and identify calls, allFlags does not send events to LaunchDarkly. Thus, users are not created or updated in the LaunchDarkly dashboard.

The allFlags method captures the state of all feature flag keys with regard to a specific user. This includes their values, as well as other metadata.

This method can be useful for passing feature flags to your front-end. In particular, you can use it to provide bootstrap flag settings for our JavaScript SDK.

1local allFlags = client:allFlags(user)


Internally, the LaunchDarkly SDK keeps an event buffer for analytics events. These are flushed periodically in a background thread. In some situations (for example, if you're testing out the SDK in a simulator), you may want to manually call flush to process events immediately.


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.


The track method allows you to record actions your users take. This lets you record events that take place on your server. In LaunchDarkly, you can tie these events to metrics in A/B tests.

Here's a simple example:

1client:track("your-goal-key", user);

You can also attach an object containing arbitrary data to your event:

1client:track("your-goal-key", user, { price = 320 } );


The identify method 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 can be useful if you want to pre-populate your dashboard before launching any features.


Database integrations

The module launchdarkly_server_sdk_redis allows feature flag data to be cached with Redis. To learn more, read Using a persistent feature store.