Application metadata configuration

Read time: 12 minutes

Last edited: Oct 02, 2024

Overview

This topic explains how to configure LaunchDarkly SDKs to send application metadata to LaunchDarkly. This feature is available for client-side and server-side SDKs.

Newer versions of LaunchDarkly SDKs replace users with contexts

A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. Contexts replace another data object in LaunchDarkly: "users." To learn more, read Contexts.

Creating contexts and evaluating flags based on them is supported in the latest major versions of most of our SDKs. For these SDKs, the code samples on this page include the two most recent versions.

Customize application information

Some LaunchDarkly SDKs support configuration options for specifying application information, including application identifier and version. When you configure these options, the SDK automatically sends this application information to LaunchDarkly.

In the LaunchDarkly user interface (UI), the application information appears in the following places:

Application information appears in the "From source" field on Context details pages. To learn more, read The context details page.
Application information appears in the Applications page. From this page, you can also set additional properties, such as whether an application version is supported or unsupported. To learn more, read Applications and application versions.

Additionally, some LaunchDarkly mobile SDKs support the automatic collection of data about the mobile environment where the application is running. When you enable this collection of environment variables, the application information that you configure here is automatically added to an ld_application context that the SDK then includes in each evaluation context. To learn more, read Automatic environment attributes.

After the SDK has evaluated at least one feature flag using an ld_application context, you can create mobile targeting rules based on application and application version information. To learn more, read Applications and application versions and Mobile app and device targeting.

For the SDKs that support this feature, you can send some or all of the following metadata:

Application identifier (string): A unique identifier representing the application where the LaunchDarkly SDK is running. For example, authentication-service.
Application name (string): A human-friendly name for the application where the LaunchDarkly SDK is running. For example, Authentication-Service.
Application version (string): A unique identifier representing the version of the application where the LaunchDarkly SDK is running. For example, you could set this to the semantic version of your application, such as 1.0.0. If you are using engineering insights, you must set the application version either to the full secure hash algorithm (SHA) of the GitHub commit for this deployment, such as a12bcde3f45ab6c789123456d78efabcde91234f, or to the tag associated with the GitHub commit for this deployment. Learn more about sending deployment information to engineering insights.
Application version name (string): A human-friendly name for the version of the application in which the LaunchDarkly SDK is running. For example, v1.

For all fields, the value can use only alphanumeric characters and hyphens -, periods ., and underscores _. Spaces are converted to hyphens.

You can set these values when you configure the SDK. All connections to LaunchDarkly from a client will send the same value to LaunchDarkly, whether the connection is through streaming, polling, or events. You cannot change the value after you configure the client.

Ensure your application identifier is unique per distributed application

We recommend that you set the application identifier to a different value for each separately distributed software binary.

For example, suppose you have two mobile apps, one for iOS and one for Android. If you set the application identifier to "example-app" and the version to "1.0" in both SDKs, then when you create a flag targeting rule based only on application information, the flag will target both the iOS and Android application. This may not be what you intend. We recommend using different application identifiers in this situation, for instance, "example-app-ios" and "example-app-android."

You can also enable automatic environment attributes, and then create flag targeting rules based on both the application information and the device information. To learn more, read Automatic environment attributes.

Configure application metadata for engineering insights

Engineering insights is an Enterprise feature

Engineering insights is available to customers on an Enterprise plan. To learn more, read about our pricing. To upgrade your plan, contact Sales.

Configuring your application metadata to send deployment information lets engineering insights track the frequency and timing of your deployments. If you set the application version to a deployment SHA or tag from GitHub, engineering insights will also track which commits and pull requests are in your deployment.

An example of deployment frequency summary in engineering insights.

To learn how to retrieve the SHA for your deployment, read Set up automated deployment detection.

Details about each SDK's configuration are available in the SDK-specific sections below:

Client-side SDKs
Server-side SDKs

Client-side SDKs

This feature is available in the following client-side SDKs:

.NET (client-side)
Android
C++ (client-side)
Flutter
iOS
JavaScript
Node.js (client-side)
React Native
React Web: The React Web SDK relies on the JavaScript SDK for this functionality.
Roku

.NET (client-side)

Expand .NET (client-side) code sample

This code sample shows you how to configure the application information:

var config = Configuration
    .Builder("mobile-key-123abc", ConfigurationBuilder.AutoEnvAttributes.Enabled)
    .ApplicationInfo(Components.ApplicationInfo()
        .ApplicationId("authentication-service")
        .ApplicationName("Authentication-Service")
        .ApplicationVersion("1.0.0")
        .ApplicationVersionName("v1")
    )
    .Build();

The application information is supported in .NET SDK v3.1.0 and later.

If you configure the application information and have enabled automatic environment attribute collection, the values you set will override any values collected automatically. The application identifier, name, version, and version name you set explicitly will be included in the ld_application context. To learn more, read Automatic environment attributes and application metadata configuration.

To learn more about the configuration option, read ApplicationInfoBuilder.

Android

Expand Android code sample

This code sample shows you how to configure the application information:

LDConfig config = new LDConfig.Builder(AutoEnvAttributes.Enabled)
    .applicationInfo(
        Components.applicationInfo()
            .applicationId("authentication-service")
            .applicationName("Authentication-Service")
            .applicationVersion("1.0.0")
            .applicationVersionName("v1")
    )
    .build();

The application identifier and version are supported in Android SDK v4 and later. The application name and version name are supported in Android SDK v5 and later.

To learn more about the configuration option, read ApplicationInfoBuilder.

C++ (client-side)

Expand C++ (client-side) code sample

This code sample shows you how to configure the application identifier and application version:

auto config_builder = client_side::ConfigBuilder("mobile-key-123abc");
config_builder.AppInfo().Identifier("authentication-service").Version("1.0.0")
auto config = config_builder.Build();

To learn more, read AppInfoBuilder.

Flutter

Expand Flutter code sample

This code sample shows you how to configure the application information:

final config = LDConfig(
  CredentialSource.fromEnvironment,
  AutoEnvAttributes.enabled,
  applicationInfo: ApplicationInfo(
    applicationId: 'authentication-service',
    applicationName: 'Authentication-Service',
    applicationVersion: '1.0.0',
    applicationVersionName: 'v1',
  ),
)

The application identifier and version are supported in Flutter SDK v2 and later. The application name and version name are supported in Flutter SDK v3 and later.

To learn more, read LDConfig.

iOS

Expand iOS code sample

This code sample shows you how to configure the application identifier and application version:

var applicationInfo = ApplicationInfo()
applicationInfo.applicationIdentifier("authentication-service")
applicationInfo.applicationName("Authentication-Service")
applicationInfo.applicationVersion("1.0.0")
applicationInfo.applicationVersionName("v1")
var config = LDConfig(mobileKey: mobileKey, autoEnvAttributes: .enabled)
config.applicationInfo = applicationInfo

The application identifier and version are supported in iOS SDK v8 and later. The application name and version name are supported in iOS SDK v9 and later.

To learn more about the specific configuration options available in this SDK, read the SDK's API docs.

JavaScript

Expand JavaScript code sample

This code sample shows you how to configure the application identifier and application version:

const options = {
    application: {
	    id: 'authentication-service',
	    version: '1.0.0',
    },
};
const client = LDClient.initialize('client-side-id-123abc', context, options);

To learn more about the specific configuration options available in this SDK, read the LDOptions.

Node.js (client-side)

Expand Node.js (client-side) code sample

This code sample shows you how to configure the application identifier and application version:

const options = {
  application: {
    id: "authentication-service",
    version: "1.0.0"
  }
};
const client = LDClient.initialize('client-side-id-123abc', context, options);

To learn more, read application.

React Native

Expand React Native code sample

This code sample shows you how to configure the application information:

const options: LDOptions = {
  applicationInfo: {
    id: 'authentication-service',
    name: 'Authentication-Service'
    version: '1.0.0',
    versionName: 'v1',
  }
}
const client = new ReactNativeLDClient('mobile-key-123abc', AutoEnvAttributes.Enabled, options);

The application identifier and version are supported in React Native SDK v7 and later. The application name and version name are supported in React Native SDK v8 and later.

If you configure the application information and specify the application id, all application information will be added to the ld_application context. Otherwise, the ld_application context will not be included. To learn more, read Automatic environment attributes and application metadata configuration.

To learn more about the specific configuration options available in this SDK, read LDOptions.

Roku

Expand Roku code sample

This code sample shows you how to configure the application identifier and application version:

' for a legacy Roku application
config = LaunchDarklyConfig("mobile-key-123abc")
' for a SceneGraph Roku Application
config = LaunchDarklyConfig("mobile-key-123abc", CLIENT_SCENEGRAPH_NODE)
' configure the application identifier and application version
config.setApplicationInfoValue("id", "authentication-service")
config.setApplicationInfoValue("version", "1.0.0")

Server-side SDKs

This feature is available for the following server-side SDKs:

.NET (server-side)
C++ (server-side)
Erlang
Go
Haskell
Java
Lua
Node.js (server-side)
PHP
Python
Ruby
Rust

.NET (server-side)

Expand .NET (server-side) code sample

This code sample shows you how to configure the application identifier and application version:

var config = Configuration.Builder("sdk-key-123abc")
    .ApplicationInfo(Components.ApplicationInfo()
        .ApplicationId("authentication-service")
        .ApplicationName("Authentication-Service")
        .ApplicationVersion("1.0.0")
        .ApplicationVersionName("v1")
    )
    .Build();
var client = new LdClient(config);

For a complete list of configuration options, read the documentation for ConfigurationBuilder.

C++ (server-side)

Expand C++ (server-side) code sample

This code sample shows you how to configure the application identifier and application version:

auto config_builder = server_side::ConfigBuilder("sdk-key-123abc");
config_builder.AppInfo().Identifier("authentication-service").Version("1.0.0")
auto config = config_builder.Build();
if (!config) {
    /* an error occurred, config is not valid */
}

To learn more, read AppInfoBuilder.

Erlang

Expand Erlang code sample

This code sample shows you how to configure the application identifier and application version:

ldclient:start_instance("sdk-key-123abc", #{
  application => #{
    id => <<"authentication-service">>,
    version => <<"1.0.0">>
  }
})

For a complete list of configuration options, read the documentation for the ldclient_config module.

Go

Expand Go code sample

The code in this sample configures the application identifier and application version:

var config ld.Config
config.ApplicationInfo.ApplicationID = "authentication-service"
config.ApplicationInfo.ApplicationVersion = "1.0.0"

To learn more about the configuration options, read Config.

Haskell

Expand Haskell code sample

This code sample shows you how to pass custom parameters to the client by creating a custom configuration object.

The code in this sample configures the application identifier and application version:

{-# LANGUAGE OverloadedStrings #-}
import LaunchDarkly.Server.Config
import Data.Function ((&))
config :: Config
config = makeConfig "sdk-key-123abc" & configSetApplicationInfo appInfo
    where appInfo = makeApplicationInfo
            & withApplicationValue "id" "authentication-service"
            & withApplicationValue "version" "1.0.0"

Java

Expand Java code sample

This code sample shows you how to configure the application identifier and application version:

LDConfig config = new LDConfig.Builder()
  .applicationInfo(
    Components.applicationInfo()
      .applicationId("authentication-service")
      .applicationVersion("1.0.0")
  ).build();

For a complete list of configuration options for the client, including proxy settings, timeouts, and streaming/polling options, read the Javadoc for LDConfig.Builder.

Lua

Expand Lua code sample

This code sample shows you how to configure the application identifier and application version:

local config = {
    appInfo = {
      identifier = "authentication-server",
      version = "1.0.0"
    }
}

To learn more about the configuration options, read clientInit.

Node.js (server-side)

Expand Node.js (server-side) code sample

This code sample shows you how to configure the application identifier and application version:

import * as ld from '@launchdarkly/node-server-sdk';
const options: ld.LDOptions = {
  application: {
    id: 'authentication-service',
    version: '1.0.0'
  }
};
const client = ld.init('sdk-key-123abc', options);

To learn more about the specific configuration options available in this SDK, read the SDK's API docs.

PHP

Expand PHP code sample

This code sample shows you how to configure the application identifier and application version:

$appInfo = (new ApplicationInfo())->withId('authentication-service')->withVersion('1.0.0');
$config = [
  "application_info" => $appInfo
];
$client = new LaunchDarkly\LDClient("sdk-key-123abc", $config);

To learn more, read ApplicationInfo. For a complete list of configuration options, read the documentation for the LDClient constructor.

Python

Expand Python code sample

This code sample shows you how to configure the application identifier and application version:

config = Config(sdk_key='sdk-key-123abc',
  application = {"id": "authentication-service", "version": "1.0.0"})
ldclient.set_config(config)

To learn more, read application. For a complete list of configuration options, read the documentation for the ldclient.config module.

Ruby

Expand Ruby code sample

This code sample shows you how to configure the application identifier and application version:

LaunchDarkly::Config.new({
  application: {
    id: "authentication-service",
    version: "abc123def456"
  }
})

To learn more about the specific configuration options available in this SDK, read the SDK's API docs.

Rust

Expand Rust code sample

This code sample shows you how to configure the application identifier and application version:

let mut application_info = ApplicationInfo::new();
application_info
    .application_identifier("authentication-service")
    .application_version("1.0.0");
let config = ConfigBuilder::new(&sdk_key)
    .application_info(application_info)
    .build();

The Config type lets you specify a variety of options. To learn more about the specific configuration options available in this SDK, read the SDK's API docs.

Application metadata configuration

Read time: 12 minutes

Last edited: Oct 02, 2024

.css-1wc0auy{padding-right:0.5rem;margin-left:-2rem;float:left;display:none;}@media screen and (min-width: 48rem){.css-1wc0auy{display:-webkit-box;display:-webkit-flex;display:-ms-flexbox;display:flex;}}Overview

Customize application information

Configure application metadata for engineering insights

Client-side SDKs

.NET (client-side)

Android

C++ (client-side)

Flutter

iOS

JavaScript

Node.js (client-side)

React Native

Roku

Server-side SDKs

.NET (server-side)

C++ (server-side)

Erlang

Go

Haskell

Java

Lua

Node.js (server-side)

PHP

Python

Ruby

Rust

Overview