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

GIVE DOCS FEEDBACK

Applications and application versions

Read time: 9 minutes
Last edited: Jun 07, 2024

Overview

This topic explains how to build and use applications. An application is a LaunchDarkly resource that describes what you are delivering to a customer. LaunchDarkly automatically creates applications when it establishes a connection with a LaunchDarkly SDK that contains application information. After an application is created, you can build flag targeting rules based on application name, version, or other properties, such as whether or not a particular application version is supported.

Applications are unique per account. This means that the same application can exist in multiple environments, across different projects.

If you use engineering insights, you can also automatically create applications when you send deployment events. To learn how, read Applications.

Common use cases

The most common use case for working with applications is when you are developing a mobile app. You can use applications to track which versions are associated with which flags, and to evaluate flags differently for supported or unsupported app versions.

Here's how:

  1. Create an application. LaunchDarkly creates applications for you based on your SDK configuration. To learn more, read Create applications.
  2. For each application, create application versions. LaunchDarkly creates application versions for you based on your SDK configuration. To learn more, read Create application versions.
  3. (Optional) In the LaunchDarkly user interface, mark whether each application version is supported or unsupported.
  4. In your feature flags, use targeting rules to define your app's behavior based on application properties. For example, you might want to serve one variation when the application version is supported, but serve a different variation if it is unsupported. To learn more, read Mobile app and device targeting.
  5. (Optional) If a feature flag is only relevant for unsupported application versions, you can deprecate the flag. To learn more, read Deprecate flags.

View applications and application versions

  1. Click the gear icon in the left sidenav to view Organization settings.
  2. Click Applications.

From the Applications list, you can find applications by name or key. You can also narrow the list by kind, or sort the list by application name or creation date. By default, the most recently created applications appear first.

When you click the name of an application in the Applications list, the application's Versions page appears. From the Versions page, you can do the following:

  • Review details on the devices using your application.
  • Review the adoption of your application by application version.
  • Filter application versions by name or key.
  • Sort the application versions by version name or creation date. By default, the most recently created application versions appear first.
The "Versions" tab for an application.
The "Versions" tab for an application.

Each application also has a History tab. This tab contains a record of the changes made in LaunchDarkly to the application or its versions.

Adoption metrics

The application's Versions page shows the adoption of your application by application version.

The adoption percentage for each application version is calculated as the ratio of:

  • the application version for each device with this application, to
  • the total devices across all versions of this application

that LaunchDarkly has seen over the past 30 days.

For example, suppose there are five devices running your application. If two of those devices are using v3.0, then the adoption percentage for v3.0 is 40%.

Because the adoption percentage only looks at the past 30 days, your adoption percentages could change over time. For example, it may look like 100% of your customers have adopted v3.0 of your app if a customer with an older version does not use the app very often.

About applications

LaunchDarkly automatically creates applications when it establishes a connection with a LaunchDarkly SDK that contains application information. You can edit and delete applications from the Applications list in the LaunchDarkly user interface (UI).

Create applications

LaunchDarkly automatically creates new applications when it establishes a connection with a LaunchDarkly SDK that supports Application metadata configuration.

We strongly recommend also enabling automatic environment attribute collection as part of your SDK configuration. When this configuration is enabled, you can create mobile targeting rules for your feature flag based on the application information. The SDK provides data on the mobile environment where an application is running, including the application name and id. The SDK includes this data in the ld_application and ld_device contexts. 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 in that context. To learn more, read Mobile app and device targeting.

Add mobile targeting rules only after application information is collected

You can only create a "Mobile" targeting rule, and target mobile apps and devices based on automatically collected application information, 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 application information 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, read Environment attributes.

Edit applications

To edit an existing application:

  1. Click the gear icon in the left sidenav to view Organization settings.
  2. Click Applications.
  3. Find the application you want to edit. Click the overflow menu and choose "Edit."
  4. In the dialog, update the Kind, Description, or Maintainer. You cannot modify the application name or key.
  5. Click Save.

You can also use the REST API: Update application

Delete applications

To delete an existing application:

  1. Click the gear icon in the left sidenav to view Organization settings.
  2. Click Applications.
  3. Find the application you want to delete. Click the overflow menu and choose "Delete application."
  4. In the dialog, type the name or key of the application to confirm.
  5. Click Delete.

You can also use the REST API: Delete application

Application versions

LaunchDarkly automatically creates application versions when a LaunchDarkly SDK evaluates a feature flag that contains application version information. You can edit and delete application versions from the Versions tab of an existing application in the LaunchDarkly UI.

Create application versions

Similar to creating an application, LaunchDarkly automatically creates new application versions when it establishes a connection with a LaunchDarkly SDK that supports Application metadata configuration.

We strongly recommend also enabling automatic environment attribute collection as part of your SDK configuration. When this configuration is enabled, the SDK provides data on the mobile environment where an application is running, including the application version name and id. The SDK includes this data in the ld_application and ld_device contexts. 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 in that context. To learn more, read Mobile app and device targeting.

Add mobile targeting rules only after application version information is collected

You can only create a "Mobile" targeting rule, and target mobile apps and devices based on automatically collected application version information, 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 application information 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, read Environment attributes.

Edit application versions

You can only edit an application version's support status. Only application versions for "mobile" application kinds include a support status.

To edit an application version:

  1. Click the gear icon in the left sidenav to view Organization settings.
  2. Click Applications.
  3. Find the application whose versions you want to edit and click its name. The application's Versions tab appears.
  4. In the list of versions, find the version you want to edit.
  5. Click the overflow menu and choose "Edit support status."
  6. In the "Edit version support status" dialog, select the new Support status.
  7. Click Save.

You cannot modify an application version name or key.

Ensure your application key is unique per distributed application

Before you mark an application version as unsupported, make sure that the application key is unique for each separately distributed software binary.

For example, suppose you have a mobile app, "Example app," that you distribute on both iOS and Android. Initially you create one application, with application key "example-app" and application version "1.0". However, if you set the "1.0" application version to unsupported, then if you create a flag targeting rule based only on the supported status, the flag will target both iOS and Android. This may not be what you intend.

We recommend that you create different applications for each separately distributed software binary, and set the application key to a different value for each. To learn more, read Application metadata configuration.

You can also use the REST API: Update application version

Delete application versions

To delete an existing application version:

  1. Click the gear icon in the left sidenav to view Organization settings.
  2. Click Applications.
  3. Find the application whose versions you want to delete and click its name. The application's Versions tab appears.
  4. In the list of versions, find the version you want to delete.
  5. Click the overflow menu and choose "Delete."
  6. In the dialog, type the name or key of the version to confirm.
  7. Click Delete.

You can also use the REST API: Delete application version