• HOME
  • INTEGRATIONS
  • SDKS
  • GUIDES
  • API DOCS
No results for ""
EXPAND ALL
launchdarkly.com

EDIT ON GITHUB

Creating your first flag

Read time: 7 minutes
Last edited: Nov 20, 2020

Overview

This guide explains how to create your first flag in LaunchDarkly and use it to control how that feature is released to users. Feature management starts with flags. Feature flags wrap your code and give you the ability to release your feature in a safe and controlled way.

In this guide, you will use Glitch to complete the process of creating a flag in LaunchDarkly, including configuring your environment and SDKs, and creating the flag itself.

You will:

  • Clone a sample web app
  • Add the LaunchDarkly SDK to the web app
  • Create and use your first LaunchDarkly feature flag
  • Turn on your first feature

Prerequisites

To complete this guide, you must have the following prerequisites:

  • An active LaunchDarkly account with the ability to create a flag.
  • Basic knowledge of the Python and Javascript programming languages. You need these to complete the exercises in this guide.
  • Access to Glitch.
See also: How to use Glitch

Concepts

Read this section to understand the way we use some terms in this guide.

LaunchDarkly data hierarchy

The basic unit of work in LaunchDarkly is a feature flag, often referred to as a flag. Flags exist inside LaunchDarkly environments, and can exist across multiple environments. All the environments in your LaunchDarkly instance are referred to as your LaunchDarkly project. A project can contain multiple environments.

Typically, most software projects have a test, staging, and production environment. In LaunchDarkly, you can define any environment structure that suits your team’s needs.

For example, your mobile team might need an android test, android prod, ios test, and ios prod environment in the "Mobile apps" project.

To learn more, read Projects and Environments.

LaunchDarkly SDK basics

The LaunchDarkly SDK is the primary tool you use to manage feature flags in your application code. The SDK is responsible for making the connection to LaunchDarkly and giving your app access to the flags defined in your environment.

After you implement the client SDK in your application code, your code can fetch a flag from LaunchDarkly and evaluate it locally to get the flag’s value for a given user or context.

To learn more, read Getting started with SDKs.

LaunchDarkly's SDK comes in a variety of client-side, server-side, and mobile implementations for different languages. This guide uses the Python SDK for our server-side code.

There are several differences between the server and client-side SDKs. Client-side SDKs are designed to run on a single-user desktop, embedded application, client-side web application, or on mobile devices.

Server-side SDKs are designed for multi-user systems and services running on a corporate network or in the cloud. Because they are designed to exist in more secure environments, and not rely on mobile data to make connections to LaunchDarkly, server-side SDKs retrieve the entire set of flag rules and evaluate the flag values for each user or context within the SDK's runtime.

Client-side SDKs receive the evaluated value of a flag for the user on the chosen application directly from LaunchDarkly. We assume that client-side SDKs are on devices that may be shared or less secure, so LaunchDarkly never transmits flag rules to client-side SDKs.

To learn more, read Understanding the different types of SDKs.

Using feature flags with variations

With LaunchDarkly's feature flags, you can develop a feature, wrap it in a feature flag, and prevent users from accessing it until you want them to. When you wrap a feature in a feature flag, you're gating access to the feature based on a condition you specify.

You can also specify multiple variations of a flag to produce different outcomes. For example, you could create three variations of the same flag, each of which shows a price page with a 10%, 15%, or 25% discount.

The simplest feature flags have two variations: true and false. These are called boolean flags. This is the kind of flag we'll use in the exercise below.

An example of a feature flag wrapped around a feature is depicted below:

1if enableFeature(on.click.checkout, {...}) then
2 /* show the new feature */
3else
4 /* show the old feature */

The ld_client has a few methods that allow your code to decide which variation of a feature to show.

An example of a variation method is depicted below:

1# flag-key: String
2# user: Python dictionary
3# default-variation: boolean, string, or dictionary
4ld_client.variation(<FLAG-KEY>, <USER>, <DEFAULT-VARIATION>)

The user property in the second parameter of the variation() method is an object that describes the user against which you want to evaluate that flag.

LaunchDarkly keeps track of this user and remembers what variation they received so your app can show them the same feature each time they visit. This also gives you knowledge about your users so you can target specific users with your new feature.

The third property, default-variation, is the value that the flag defaults to if ldclient encounters an error. For example, if the feature flag key doesn't exist or the user doesn't have a key specified, LaunchDarkly returns the default flag variation.

Exercise: Using the LaunchDarkly SDK

In this exercise, we'll implement a pricing page on a mock online store. You will introduce a new pricing tier, wrap the code for it in a feature flag, and release it to users by enabling the flag.

This exercise uses a Python-based web application we provide and runs on Glitch, an online tool for creating web apps.

Space Camp pricing page
Space Camp pricing page

Remixing the lab app

You must remix the Glitch project embedded below to create an editable copy of the Python web app. Remixing is Glitch's term for cloning a project. This creates an editable copy of the Python web app we use for this exercise.

Click this link to remix the app, or follow the instructions below.

  1. Click the fullscreen button in the bottom right-hand corner of the Glitch app embedded above. app. The app opens in a separate tab.
  2. In the new Glitch tab, click Remix to Edit.
  3. The name of your project appears in the top left corner. If you want to rename the app, click the arrow next to the name.

Switching between the code and app views in Glitch

In the Glitch app, you have the option to see the live app in production, or the code for the app.

To switch between them:

  1. Navigate to the Glitch app you remixed.
  2. At the top of the Glitch page, click Show:

The "Show" menu in Glitch.
The "Show" menu in Glitch.

  1. Confirm that you can switch between the code and the app view.

Setting up your LaunchDarkly project and environment

You must set up a LaunchDarkly project and environment where your flags will live. Create a new project or use an existing one in your account.

To create a new project:

  1. Navigate to the Account settings page.
  2. Click + Project.
  3. Give your project a human-readable Name. In the example below, our project is called Test.
  4. Click Save.
  5. In the Account Settings page, click to copy the new project's SDK key to your clipboard.

The Account Settings page in LaunchDarkly with environment SDK keys called out.
The Account Settings page in LaunchDarkly with environment SDK keys called out.

Configuring the LaunchDarkly SDK key in your app

Glitch lets you store environment variables, such as secrets or config variables, that your app can read from memory. This is a more secure practice than hard-coding these directly into your code.

To learn more about environment variables in Glitch, read Glitch's documentation.

  1. Click the .env file in the Glitch sidebar.
  2. Assign the SDK key you copied above to an environment variable called LD_SDK_KEY:
1LD_SDK_KEY=<PASTE-YOUR-SDK-KEY-HERE>

The .env file in Glitch.
The .env file in Glitch.

Installing the Python SDK in your code

Now you must install the LaunchDarkly Python SDK in your Python code. To do this, add the LaunchDarkly Python SDK as a dependency to the Python app by adding the following line to the requirements file.

1launchdarkly-server-sdk

The requirements file defines all of the Python modules the app you're building depends on.

This app is configured to install dependencies and restart when certain of its files change. You do not need to refresh or reinstall anything.

To verify a successful installation, open the the log console in Glitch:

  1. Click Tools in the bottom left hand corner.
  2. Select Logs.

If you configured the Python SDK correctly, you will see a message indicating that launchdarkly-server-sdk was installed.

Initializing the LaunchDarkly client

After you install the SDK, you can import the LaunchDarkly client into your code and initialize it.

To do this:

  1. Add the following line to the top of your server.py file:
1import ldclient
2...
  1. Specify your SDK key to connect the SDK to LaunchDarkly.
1...
2# Paste your SDK key inside the `.env` file. Don't paste it
3# here or you'll expose your SDK key to anyone who opens
4# this app. Instead, use the environment variable to
5# reference the SDK key, as shown in the example below:
6ldclient.set_sdk_key(os.getenv('LD_SDK_KEY'))
7
8# We will use this client from now on:
9ld_client = ldclient.get()

You've initialized the ldclient. Next, use the client to wrap your app's new pricing tier inside a flag.

Creating a new flag

Before you add code to the pricing page, create a new flag in your project. Name the flag pricing-tier-3.

Here's how to create the new flag:

  1. From the LaunchDarkly app, click Feature flags.
  2. Click + Flag.
  3. Enter pricing-tier-3 for the name.
  4. Optionally, add a description of the flag.
  5. Leave the flag variation set to Boolean.
  6. Save the new flag.

The flag's targeting state is set to off by default. You can turn it on after implementing the code to use it.

The new flag is pictured below:

pricing-tier-3 flag
pricing-tier-3 flag

Adding a new pricing tier

You're now ready to add the new pricing tier to the pricing page. To do this, you'll add the HTML for the new page to your app, but only after wrapping it in a feature flag so only intended users can see it.

The updated pricing tier page is pictured below:

The new pricing tier.
The new pricing tier.

It uses the following HTML:

1<!-- Admiral Tier -->
2<div class="card h-100">
3 <div class="card-body">
4 <h5 class="card-title text-center">
5 Admiral Class
6 </h5>
7 <h6 class="card-price text-center">
8 <i class="fab fa-btc"></i> 250,000
9 </h6>
10 <hr />
11 <ul class="fa-ul">
12 <li>
13 <span class="fa-li"><i
14 class="fas fa-space-shuttle"></i></span>Shuttle-class
15 x701 space coach
16 </li>
17
18...
19
20 <li>
21 <span class="fa-li"><i class="fab fa-grav"></i></span>Space walk experience
22 </li>
23 </ul>
24 </div>
25 <div class="card-footer">
26 <a id="tier3" href="#"
27 class="btn btn-block btn-primary">Select class</a>
28 </div>
29</div>

This HTML is also available in your Glitch app, in views/ > tier_3.html.

Wrapping the pricing page code in a flag

Now you wrap the HTML for the new pricing page in a flag. This prevents anyone who is not targeted by the flag from seeing the new pricing page.

Use the following server.py code:

1@app.route('/')
2def pricing():
3 """Displays the pricing page."""
4
5 # Implement the feature flag here
6 return render_template('pricing.html')

The code above shows the controller handler for the pricing page route to the web app. All this handler does is return the rendered pricing.html template to the user.

The following code sample shows an instruction to evaluate the flag, then pass the result of the evaluated flag into the page template.

1@app.route('/')
2def pricing():
3 """Displays the pricing page."""
4
5 # Since this page doesn't require a logged in user,
6 # tell LaunchDarkly that this is an anonymous user.
7 user = {
8 "key": "anon",
9 "anonymous": True
10 }
11 is_tier_3_enabled = ld_client.variation('pricing-tier-3', user, False)
12 return render_template('pricing.html', is_tier_3_enabled=is_tier_3_enabled)

The controller passes the evaluated flag value to the template named is_tier_3_enabled.

Now update the pricing.html template to determine if the new pricing tier should be displayed.

The updated template should look like this:

1{% extends "base.html" %}
2{% block main %}
3<section class="pricing py-5">
4 <div class="container">
5 <div class="row justify-content-center">
6 <div class="card-group">
7
8 {% include "tier_1.html" %}
9 {% include "tier_2.html" %}
10
11 {# Tier 3 is now controlled by a feature flag! #}
12 {% if is_tier_3_enabled == True %}
13 {% include "tier_3.html" %}
14 {% endif %}
15
16 </div>
17 </div>
18 </div>
19</section>
20{% endblock %}

After you've implemented the changes above, refresh the browser with your Glitch app in it.

Verify that the new tier is not enabled. The pricing page should not show the new pricing option yet.

Turning your feature on

Now that you've wrapped your feature in a flag, it's time to turn your feature on. This will make the new pricing option appear in your app.

To do this, return to the LaunchDarkly app.

  1. Navigate to the pricing-tier-3 flag.
  2. Click the Targeting toggle to toggle the flag to on.
  3. Enter a comment.
  4. Click Turn on.
  5. Refresh the browser with your Glitch app in it again to verify that the new pricing tier is available.


Conclusion

In this tutorial, you learned to:

  • Add the LaunchDarkly SDK to your application
  • Create and use a feature flag
  • Test your feature flag to confirm that it works

You now have the basics you need to complete the next tutorial, Flag rules and targeting.

Want to know more? Start a trial.

Your 14-day trial begins as soon as you sign up. Learn to use LaunchDarkly with the app's built-in quick start guide. You'll see how easy it is to manage the whole feature lifecycle from concept to launch to control.

Want to try it out? Start a trial.