No results for ""
EXPAND ALL
  • Home
  • API docs

Automatic environment attributes

Read time: 8 minutes
Last edited: Jul 13, 2024

Overview

This topic explains how LaunchDarkly automatically provides data about the environment where the application is running.

Some LaunchDarkly mobile SDKs support automatically providing data about the environment where the application is running. This data makes it simpler to target your mobile customers based on application name or version, or on device characteristics including manufacturer, model, operating system, locale, and so on.

When you configure your SDK, you must explicitly decide whether or not LaunchDarkly should collect and return this data. We recommend enabling this feature when you configure the SDK.

After you enable this option, the SDKs automatically add this data to each evaluation context you provide. The data is provided in two new context kinds: ld_application and ld_device. If the data is not available, it is omitted.

Customers who are billed by primary context kind may be charged based on the ld_device context kind if it becomes the context kind with the highest volume of monthly activity in their account. This feature does not affect customers on other billing models. To learn more, read Account usage metrics.

Add mobile targeting rules only after environment attributes are collected

You can only create a "Mobile" targeting rule, and target mobile apps and devices based on automatically collected mobile environment attributes, if you have completed the following:

  • your feature flag has its Client-side SDK availability set to include "SDKs using Mobile key." To learn more, read Creating new flags.
  • you have already started to collect these attributes in the ld_application and ld_device context kinds. LaunchDarkly must receive these context kinds before it enables the option to create a mobile targeting rule. To learn more about mobile targeting rules, read Mobile app and device targeting.

To use this feature, you must:

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

About the automatically added environment attributes

If you enable automatic environment attributes in the SDK client configuration, the SDK automatically adds additional contexts to each context that you evaluate. You can use attributes from these contexts in your targeting rules.

These automatically added contexts include the following attributes:

Context kindContext attributeDescriptionExamples
ld_applicationkeyUnique for this context kind. Automatically generated by the SDK.randomly generated
idUnique identifier of the application.com.launchdarkly.example
localeLocale of the device, in IETF BCP 47 Language Tag format.en-US
nameHuman-friendly name of the application.Example Mobile App
versionVersion of the application used for update comparison.5, 1.2.3
versionNameHuman-friendly name of the version. May or may not be a semantic version.5, 1.2
envAttributesVersionVersion of the environment attributes schema being used. This may change in later versions of the SDK.1.0
ld_devicekeyUnique for this context kind. Automatically generated by the SDK. May be regenerated in some cases, for example, if a customer uninstalls and then re-installs the application, or if a customer purchases a new device and doesn't restore the device from their prior device's backup.randomly generated
manufacturerManufacturer of the device.Google, Apple
modelModel of the device.Pixel 6 Pro, iPhone, iPhone10,3
osOperating system of the device. Includes properties for family, name, and version.
  • family: Android, Apple
  • version: 13, 16.2
  • name: Android, Android33, iOS
envAttributesVersionVersion of the environment attributes schema being used. This may change in later versions of the SDK.1.0
Working with multi-contexts

When you enable environment attributes, the SDK automatically adds the ld_application and ld_device contexts to the evaluation context that you pass to variation calls.


This means every evaluation context is now a set of multiple contexts, which is called a multi-context. You can create targeting rules in your feature flags based on data from multiple contexts at the same time. To learn more, read Multi-contexts.


If the LaunchDarkly SDK you are using does not support environment attributes, you can create a multi-context yourself when you construct the evaluation context. You can include similar attributes as are included in the environment attributes feature, if you have access to them from your application, or you can include others. However, you must use the environment attributes feature in order to create mobile targeting rules.

If the SDK cannot determine the information for a particular attribute, it will not include that attribute. For example, if the SDK cannot determine the device's model, it will not include the model attribute.

If the SDK can determine none of the information for an entire context, it will not include that context. For example, if you run the .NET (client-side) SDK on a desktop environment, the SDK cannot reliably get the device information. In this case the ld_device context is omitted.

Automatic environment attributes and application metadata configuration

If you are already setting application metadata as part of your SDK configuration, you can still use the environment attributes feature. Any application metadata that you set will override the automatically collected environment attributes.

Specifically, if you enable automatic environment attributes, then the ld_application context attributes are set based on the following priority order:

  1. If you set values for application id, name, version, or version name using application metadata configuration in the SDK, then the ld_application context will reflect those values.
  2. Otherwise, if you have set values for the application id, name, version, or version name within your mobile app, the ld_application context will reflect those values.
  3. Otherwise, the ld_application context will use the LaunchDarkly SDK name and version.
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, by setting "example-app-ios" and "example-app-android" in your application metadata configuration. Alternatively, you can create flag targeting rules based on a combination of the ld_application information and the ld_device information.

Client-side SDKs

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

.NET (client-side)

Expand .NET (client-side) code sample

This feature is available in v4 and later of the .NET (client-side) SDK.

.NET (client-side) SDK returns different values in v4 and v5

After you upgrade from version 4 to version 5 of the LaunchDarkly .NET (client-side) SDK, the SDK returns different values for some of the environment attributes:

  • For Android, the ld_device attribute os/name now returns only the name. For example, the version 5 SDK returns Android, while the version 4 SDK returns Android28 or similar. Use the ld_device attribute os/version to access the version information.
  • For iOS, the ld_device attribute model now returns model numbers in some cases. For example, the version 5 SDK returns iPad5,2 or iPhone10,3, while the version 4 SDK returns iPad or iPhone.
  • For iOS, the ld_application attribute name is populated as follows:
    • ld_application.name returns the name that you set using application metadata configuration in the SDK, if any.
    • If that is not set, then the version 5 SDK returns the CFBundleDisplayName if defined. Otherwise, it returns the CFBundleName. This is a change in behavior. The version 4 SDK always returns the CFBundleName.
    • If that is not set, ld_application.name returns the LaunchDarkly SDK name and version.

Because of these changes, you should check your mobile targeting rules carefully after you upgrade your SDK. To learn more about upgrading, read .NET (client-side) SDK 4.x to 5.0 migration guide.

This code sample shows you how to configure the SDK to record environment attributes from an end user's mobile device:

var config = Configuration
.Builder("mobile-key-123abc", ConfigurationBuilder.AutoEnvAttributes.Enabled)
.Build();

To disable this option, pass in AutoEnvAttributes.Disabled instead.

To learn more, read Configuration.

Android

Expand Android code sample

This feature is available in v5 and later of the Android SDK.

This code sample shows you how to configure the SDK to record environment attributes from an end user's mobile device:

LDConfig ldConfig = new LDConfig.Builder(AutoEnvAttributes.Enabled)
.mobileKey("mobile-key-123abc")
.build();

To learn more, read LDConfig.Builder.

Flutter

Expand Flutter code sample

This feature is available in version 3 and later of the Flutter SDK.

This code sample shows you how to configure the SDK to record environment attributes from an end user's device:

final config = LDConfig(CredentialSource.fromEnvironment, AutoEnvAttributes.enabled)

To learn more, read LDConfig.

iOS

Expand iOS code sample

This feature is available in v9 and later of the iOS SDK.

This code sample shows you how to configure the SDK to record environment attributes from an end user's mobile device:

let config = LDConfig(mobileKey: "mobile-key-123abc", autoEnvAttributes: .enabled)

To learn more, read LDConfig.

React Native

Expand React Native code sample

This feature is available in v8 and later of the React Native SDK.

This code sample shows you how to configure the SDK to record environment attributes from an end user's mobile device:

const client = new ReactNativeLDClient('mobile-key-123abc', AutoEnvAttributes.Enabled, options);
Set application metadata to include ld_application

In version 10 of the React Native SDK, the ld_application context is only included if you set the application id using application metadata configuration when you construct the client. The SDK does not automatically populate the ld_application context with values from your mobile app or from the SDK itself.

To learn more, read ReactNativeLDClient.