Feature flags

A Feature Flag is a toggle for controlling the availability of content or functionality in your app or website. iOS SDK 17.1+Android SDK 17.1+

 Important

Feature Flags are available for Airship customers participating in our special access program. Sign up here

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.

You can also use Feature Flags to determine a messaging audience or trigger automation. See Using Feature Flags with messaging.

Audience and scheduling

Flags can be open-ended or time-bound, starting immediately or at a scheduled time and date.

When creating a flag, set your audience to members of a Test GroupA preview group is audience group used for previewing personalized content in the dashboard. Wherever a personalization preview is available, you can select a preview group, and its group members’ attributes will appear for any Handlebars references to attributes. You can enable any preview group as a test group so you can send test messages to its group members. 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. Any user included in the set percentage are considered eligible, meaning they have access to the feature.

Setting a percentage helps you limit the audience so you can effectively manage feedback or limit exposure to potential bugs. For feature rollout, gradually increase the percentage to expand your audience.

You can also set conditions audience members must meet in order to experience the feature the flag controls. For example, you could set a condition where only users who have freshly installed your app will be able to access the flagged feature. If you also set a percentage of 10%, only 10% of users who meet the condition will be able to access the feature.

For more about audience and eligibility, see Example use case below.

Supported conditions per channel:

ConditionSupported Channels
App versionApp
Device tagsApp, Web
LocaleApp, Web
Location opt-in statusApp, Web
New usersApp, Web
PlatformsApp, Web
Push opt-in statusApp, Web
SegmentsApp iOS SDK 17.6+Android SDK 17.5+

Interaction events

Track interaction with the flagged feature by generating an event from the mobile SDK. It must be explicitly called by the developer. See Tracking Interaction in our Mobile platform documentation. Contact Support for Web implementation.

While it is called an “interaction” event, what you track is up to you and depends on the feature. Some examples of how to implement different use cases:

  • Tracking when a user encounters a change — For a flag that changes a button’s color from blue to green or adds a new button to a screen, track when a user visits the screen containing the button, since it is a visible change.

  • Tracking when a user interacts with a change — For a flag that changes a button’s destination, track when the user selects the button, since it is a non-visible change.

The events have a flag ID and flag name, which identify which flagged feature a user interacted with. They also have a boolean eligible field, which indicates whether or not the user was in the Feature Flag audience and had access to the feature. See also 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.

Deciding what you are tracking is especially important when using the flag to trigger a message, since you can trigger based on whether or not the user is part of the Feature Flag audience.

Workflow

The following is the general workflow for using Feature Flags.

  1. Create a flag in the dashboard, setting your audience to members of a Test GroupA preview group is audience group used for previewing personalized content in the dashboard. Wherever a personalization preview is available, you can select a preview group, and its group members’ attributes will appear for any Handlebars references to attributes. You can enable any preview group as a test group so you can send test messages to its group members. These messages appear as tests in Messages Overview. .

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

  2. Give the code snippets and Mobile docs link to your developer for implementation.

  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.

  4. After verifying the feature works as intended with your Test Group, change the audience to Target Specific Users and set the percentage and conditions. Manage the flag from the Airship dashboard. You can turn it on and off, adjust the audience, change the schedule, etc.

  5. After the flag has served its purpose, archive it and remove the flag code from your app or website.

Draft flags

To save a flag as a draft, complete at least the first configuration step, then select Exit.

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

Example use case

This example is for introducing a redesigned Settings screen in a mobile app.

To let all new users experience the new Settings screen, set up the audience and interaction event like this:

Flag audienceInteraction event
1. Select Target Specific Users.
2. Set the audience percentage to 100.
3. Add the condition New users.
Track when users view the Settings screen.

100% of users who have freshly installed your app will be able to see the redesigned Settings screen. They are eligible users. For each interaction event:

  • When eligible has a value of true, that means the screen was viewed by a member of the Feature Flag audience. The user experienced the redesigned Settings screen.

  • When eligible has a value of false, the screen was viewed by a user that is not in the Feature Flag audience. The user saw the old version of the Settings screen.

However, if you’re concerned about the potential for bugs in the redesigned screen, you would want to limit how many new users could see it. Keep all the settings the same except the percentage, which you would set to 10. 10% of users who have freshly installed your app will be able to see the redesigned Settings screen.

Once you determine the feature is ready for a wider audience, edit the flag and increase the audience percentage. Keep adjusting till you reach 100% or the acceptable threshold determined by your planning.

Creating Feature Flags

You can create up to 100 Feature Flags.

  1. Go to Experiments, then Feature Flags.

  2. Select Create Feature Flag. After completing each step, select Next to move on.

  3. Configure for the flag:

    Field or SectionDescriptionConfiguration
    Display nameDashboard label for the flag.Enter text.
    Flag nameThe name used for reference by the SDK. Must be unique. Automatically generated based on the display name, but you can change it. The name can contain letters, numbers, and underscores only, and it must start with a letter and end with a letter or number. You cannot change the flag name after making the flag active.Enter text.
    DescriptionDescribes what the flag controls.Enter text.
    Reference imageOptional. A screenshot that shows how the feature will appear to your audience. The image appears in the dashboard only.Upload an image file.
  4. Select and configure the audience:

    OptionDescriptionConfiguration
    Test UsersMakes the feature available to users in a Test Group.Select a test group.
    Target Specific UsersMakes the feature available to random users for a percentage of your total app or web audience. If you set conditions, the percentage applies to the group of users who meet the conditions.Set a percentage. For conditions, configure according to the steps in Target Specific Users: In-App Experiences. See Audience and scheduling for the list of conditions.
  5. Schedule the period when the flag will be active. For specific times and dates, also specify the time zone. The UTC conversion displays below the settings and updates as you make changes.

  6. Review your flag settings and copy the code snippets for your developer. Select 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 dashboard to get the code snippets at any time:

  1. Go to Experiments, then Feature Flags.
  2. Select the pencil icon () for a flag. It will open to the Review step.
  3. Copy the code snippets.
  4. Select Exit.

Using Feature Flags with messaging

You can use a flag’s audience as the audience for an In-App AutomationMessages that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. or SceneMulti-screen experiences that are cached on users’ devices and displayed when your users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. Scenes can include survey questions or be presented as a story. . See the Audience step in each Create guide:

You can also trigger an In-App Automation, Scene, or SequenceA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. when an interaction event occurs. See the Feature Flag Interaction Event trigger in each Triggers guide:

Example campaign strategy

For feature roll-out in an app, your developer would implement tracking when users view the screen containing the new feature. Your campaign strategy could look like this:

  1. Inform users of the new feature — Create an In-App Automation or Scene with these settings:

    • Audience: Select Feature Flag Audience and select your flag.
    • Content: Tell your users about the feature, explain its benefits, and encourage use.
    • Behavior: Select the App Update trigger, specify the version of your app that contains the feature and flag code, and enter the number of times users must open your app before they will see your message.

    The feature will be available to the Feature Flag audience after they install the version of your app that contains the feature and flag code and according to the flag’s schedule. The message will display for the user after the number app opens you specified when setting up the trigger.

  2. Trigger a survey — Create a Scene that requests feedback from Feature Flag Audience members who have seen or interacted with the flagged feature:

    • Audience: Select Feature Flag Audience and select your flag.
    • Content: Add questions or an NPS survey about their experience with the feature.
    • Trigger: Select the Feature Flag Interaction Event trigger (the flag you selected in the Audience step will be preselected for the trigger), select the user group Users with feature access, then enter the number of times the event must occur before the Scene is triggered.

    The Scene will display for members of the Feature Flag Audience after the number of event occurrences you specified when setting up the trigger.

Maximize adoption by designing a JourneyA continuous user experience of connected Sequences, Scenes, Surveys, and/or In-App Automations. that combines the above with a SequenceA series of messages that is initiated by a trigger. Airship sends messages in the series based on your timing settings, and you can also set conditions that determine its audience and continuation. Sequences can be connected to each other and to other messaging components to create continuous user experiences in a Journey. that follows a user’s interaction with the flagged feature and sends a customized message for each key step along the way.

Managing Feature Flags

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

  • Display and flag names
  • Start and end dates and times in UTC
  • Audience — “Test group” or percentage
  • Status — Active, Scheduled, Draft, or Ended

Flag management options:

OptionDescriptionConfiguration
DuplicateThe display and flag names for duplicates are appended with "copy".Select the duplicate icon () and configure as you would a new flag.
EditYou can change a flag's display name, description, audience, or schedule settings. You can also change the flag name if the flag is not yet Active. You cannot edit archived flags.Select the pencil icon (), make your changes, then select Update flag in the Review step.
End/CancelImmediately end Active flags and cancel Scheduled flags. You can also update the end date for an ended flag, making it Active or Scheduled again.Select the pencil icon (), then End flag.
ArchiveHide Draft and Ended flags from your list of flags.Select the archive icon ().
Restore/UnarchiveRestore an archived flag to your list of flags.Select the Archived filter, then select the archive icon () for a flag.

Additional options for flags used as the audience for an In-App Automation or Scene:

OptionDescriptionConfiguration
View related messagesMessages are listed by name, type, and status. You can also open them to check for conflicts between the flag and message schedules.Select the link icon () to view the list, then select a message name. The message opens to its composer's Review step. See Schedule and compare the start and end settings.
Cancel related messagesCanceling a message is effectively the same as setting an end date for the current date and time. Messages are listed by name, type, and status. You can only cancel Active messages.

See also Restart an In-App Automation, Scene, or Survey in Change message status.

Select the archive icon (), then select   Stop for an Active message or   Stop all for all Active messages.