Feature flags

About feature flags

The format of a feature flag is a conditional if statement you add to your app code. It contains your flag name and wraps around the app code you want the flag to control.

After adding the flag to your app, you can manage the feature’s audience and schedule from the Airship dashboard. If something unexpected happens with the feature, or if you have reason to end access before its scheduled end time, you can turn it off for all users instantly, without having to release an app update and waiting for users to install the new version.

Use feature flags for:

• Premium features — Provide premium feature access only to paid users based on membership tiers.
• Phased releases — Release features to segments of your audience over time to prevent a strain on resources, such as database queries, support tickets, or limited initial product supply.
• Time-limited promotions — Turn on and off features that are meant to be time-restricted, manually or using an automated schedule, such as displaying a promotional banner only during a sale weekend.
• Testing — Test features with a small segment of your audience before releasing the feature to the rest of your audience.

Audience and scheduling

When creating a flag, you can set your audience to members of a Test GroupA preview group is an audience group you create for previewing personalized content in the dashboard. Wherever a personalization preview is available, you can select a preview group, and those users’ attributes will appear for any Handlebars references to attributes. You can enable any preview group as a test group so the users can receive test messages sent to the group. These messages appear as tests in Messages Overview. . When you are ready to go live, set a percentage of your total audience that will be able to view the feature determined by the flag. Audience members are randomly selected. You can also set conditions audience members must meet in order to experience the feature the flag controls:

• App version
• Locale
• Location opt-in status
• New users
• Platforms
• Push opt-in status
• Tags

You can create open-ended or time-bound flags, starting immediately or at a scheduled time and date.

Reporting

A feature flag interaction event occurs when a user interacts with a feature flag. The event has a flag ID and flag name, which provide information about the feature flag that a user interacted with. The event also has an eligible field, which indicates whether or not the user was eligible for a feature flag. See Feature Flag Interaction Event in the Real-Time Data StreamingA service that delivers engagement events in real time via the Data Streaming API or an Airship partner integration. API reference.

The event is generated from the mobile SDK and must be explicitly called by the developer. See: Mobile: Feature flags: Tracking Interaction.

Workflow

The following is the general workflow for using feature flags.

1. Create a flag in the dashboard.

2. In the Review step when creating the flag, copy the iOS, Android, and web code snippets and Mobile docs link and give them to your developer. All three snippets are available even if they are not configured for your Airship project. You can also access the code after saving.

3. Add the flag to your app or website. This step is usually performed by a developer.

After you update your website with the flag code, the feature will be available to the configured audience the next time they visit the site, according to the flag’s schedule. For apps, the same is true after users install the version of your app that contains the feature and flag code. Manage the flag from the Airship dashboard.

Creating feature flags

You can create up to 10 feature flags.

1. Go to Experiments » Feature Flags and click Create feature flag.

2. Define the flag:

   • Display name — This appears in the dashboard only.
   • Flag name — The name used for reference by the SDK. This name is automatically generated based on the name, but you can edit it. You cannot change the flag name after making the flag active.
     • Must be unique.
     • A flag name will not generate for a display name that contains only numbers and/or special characters.
     • Letters, numbers, and underscores only, and must start with a letter and end with a letter or number.
     • If the display name starts with a number and/or special characters, the generated flag name omits the leading numbers and/or special characters.
     • Uppercase letters in the display name are converted to lowercase in the flag name.
     • Special characters in the display name are converted to underscores in the flag name and only appear if followed by numbers or letters.
   • Description — Describe what the flag controls.
   • Reference image — Optional. Upload a screenshot of how the feature will appear to your audience. The image appears in the dashboard only.

   Click Next to move on.

3. Select and configure your audience:

   • Test Users — A predefined recipient group. After choosing Test Users, select a test group. Preview and Test Groups.
   • Target Specific Users — Set the audience percentage. If you also want to add conditions, configure according to the steps in Target Specific Users: In-App Automation.

   Click Next to move on.

4. Set the schedule. For specific times and dates, also specify the time zone. The UTC conversion displays below the settings and updates as you make changes.

   Click Next to move on.

5. Review your flag settings and copy the code snippets for your developer. Click Create and launch to make the flag active or Exit to save it as a draft. See the status information in Managing feature flags.

Implementing the code

For information about accessing flags in the SDKs and error handling, see Feature Flags in our Mobile platform documentation. Contact Support  for Web implementation.

You can return to the UI to get the code snippets at any time. Go to Experiments » Feature Flags, click   for the flag, and copy the code in the Review step. Click Exit to close.

Managing feature flags

Go to Experiments » Feature Flags to view a list of your flags. The default sort order is by last modified, and each row displays:

• Display and flag names
• Start and end dates in UTC
• Audience percentage
• Status — Active, Scheduled, Draft, or Ended. When creating a flag, you can exit before clicking Create and launch to save it as a draft. Otherwise, it will become active according to its schedule.
   Tip

  You can add flag code to your app even while it is in Draft state, then make it active after delivering your new code to devices in an app update.

Options:

• Duplicate — Click   and configure as you would a new flag. The display and flag names are appended with copy.

• Edit — You can edit a flag’s display name, description, audience or schedule settings. You can also edit the flag name if the flag is not yet active. Click  , make your changes, then click Update flag in the Review step. You cannot edit archived flags.

• End/Cancel — You can immediately end Active flags and cancel Scheduled flags. Click  , then End flag. You can update the end date schedule for an ended flag, making it active or scheduled again.

• Archive — You can archive Draft and Ended flags. Click   for a flag.

To restore archived flags, select the Archived filter and click   for a flag.