Automatic environment attributes
Read time: 5 minutes
Last edited: Sep 22, 2023
Overview
This topic explains how LaunchDarkly automatically provides data about the mobile environment where the application is running.
Some LaunchDarkly mobile SDKs support automatically providing data about the mobile 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.
This data is provided in two new context kinds, ld_application and ld_device. The SDKs automatically add this data to each evaluation context you provide. When you configure the 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. There is no charge for additional unique context instances introduced only because of these context kinds. To learn more, read Calculating client-side MCI.
To use this feature, you must:
- Use a supported client-side SDK
- Configure your SDK to enable collection of these environment attributes
Details about each SDK's configuration are available in the SDK-specific sections below.
Understanding the automatically added environment attributes
If you enable autoEnvAttributes 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.
Because the SDK automatically adds contexts, every evaluation context is now a set of multiple contexts, which is called a multi-context. This means to you can create targeting rules in your feature flags based on data from multiple contexts at once. To learn more, read Multi-contexts.
These automatically added contexts include the following attributes:
| Context kind | Context attribute | Description | Examples |
|---|---|---|---|
ld_application | key | Unique for this context kind. Automatically generated by the SDK. | randomly generated |
id | Unique identifier of the application. | com.launchdarkly.example | |
locale | Locale of the device, in IETF BCP 47 Language Tag format. | en-US | |
name | Human-friendly name of the application. | Example Mobile App | |
version | Version of the application used for update comparison. | 5, 1.2.3 | |
versionName | Human-friendly name of the version. May or may not be a semantic version. | 5, 1.2 | |
envAttributesVersion | Version of the environment attributes schema being used. This may change in later versions of the SDK. | 1.0 | |
ld_device | key | Unique for this context kind. Automatically generated by the SDK. | randomly generated |
manufacturer | Manufacturer of the device. | Google, Apple | |
model | Model of the device. | Pixel 6 Pro, iPhone | |
os | Operating system of the device. Includes properties for family, name, and version. |
| |
envAttributesVersion | Version of the environment attributes schema being used. This may change in later versions of the SDK. | 1.0 |
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.
Automatic environment attributes and application metadata configuration
If you are already setting application metadata as part of your SDK configuration, you can still use this new environment attributes feature. Any application metadata that you set will override the automatically collected environment attributes.
Specifically, ld_application context attributes are set based on the following priority order:
- If you set values for application id, name, version, or version name using application metadata configuration in the SDK, then the
ld_applicationcontext will reflect those values. - If you set values for the application id, name, version, or version name within your mobile app, the
ld_applicationcontext will reflect those values. - Otherwise, the
ld_applicationcontext will use the LaunchDarkly SDK name and version.
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 both the ld_application information and the ld_device information.
Client-side SDKs
This feature is available in the following client-side SDKs:
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 v3 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 mobile device:
LDConfig config = LDConfigBuilder('mobile-key-123abc', AutoEnvAttributes.Enabled).build();
To learn more, read LDConfigBuilder.
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
let config: ld.LDConfig = {mobileKey: 'mobile-key-123abc',enableAutoEnvAttributes: true,};
To learn more, read LDConfig.