Feature Flags

About Feature Flags

The format of a Feature Flag is a conditional if statement you add to your app or website. It contains your flag name and any properties and wraps around the code you want the flag to control. Airship provides the flag as a code snippet for your developer to add to your app or website.

Setting up a flag in the dashboard has two parts:

1. Defining the flag — Set the flag’s name, description, and properties that can be used by your app or website code within the flag.
2. Creating one or more Configurations for the flag — Determine the audience, schedule, and property values for that Configuration only.

   You can create separate Configurations for different uses of a flag, such as presenting different versions of your loyalty program to your Gold and Silver users. Arrange Configurations in order of priority to determine which Configuration should display to a user if they are included in multiple Configuration audiences. Each flag can have up to 10 Active Configurations.

After adding the flag to your app or website, you can manage a Configuration’s audience, schedule, and properties 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 easily disable it for all users. For apps, this means eliminating the need to release an app update and waiting for users to install the new version.

Flags can be open-ended or time-bound, starting immediately or at a scheduled time and date. You can also use Feature Flags to determine a messaging audience or trigger automation.

Audience

When creating a flag Configuration, 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, select All Users for your entire audience or select Target Specific Users and set conditions, then set a percentage of your set 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. 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 set a percentage of 10%, only 10% of users who meet the condition will be able to access the feature.

For flags with multiple Configurations, if a user falls into more than one Configuration’s audience, only the one with the highest priority will be active for that user. By default, each new Configuration is set to the lowest priority. See Set priority order in Managing Configurations below.

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

Supported channels per condition:

Properties

You can add properties that can be used by your app’s or website’s code within a Feature Flag, bypassing the need for traditional code changes and release processes. The flag code you pass on to your development team includes references to the properties. Once implemented, edit the flag Configuration’s properties in the dashboard to make immediate changes to your app or website, like variables that can be updated remotely. As a general example, you could create properties for a promotion’s title, description, and button URL, then change their values when the promotion ends and a new one launches.

When creating or editing a flag, set a name, type, and default value for each property. Properties can be a string, number, boolean, or JSON. You can create up to 50 properties per flag.

Properties use cases:

• Coffee mobile ordering app — Create a flag with properties for controlling the promotions and rewards for loyalty membership. Using just the Airship dashboard, you can transition from pumpkin spice promotions to holiday themes in sync with seasonal campaigns. Celebrate special limited time milestones, such as the app’s 10th anniversary, by offering “10x rewards” points.

• Music streaming app — Create a flag with properties to introduce a new premium subscription tier. Launch the feature to 25% of the audience, with flag properties “Price Point” and “Trial Period Duration” and quickly gauge engagement data and user feedback as users respond to the new tier. Update the properties to fine tune the subscription offer, and roll out the feature to 100% of users once you land on the right details. You can also use a “Promotional Messaging” property to periodically update the copy promoting the new subscription.

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.

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.

Draft Configurations

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

Workflow

The following is the general workflow for using Feature Flags:

1. Create a flag in the dashboard.

2. Create at least one Configuration, setting the 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 code snippets and Mobile docs link. Code is provided for Android (Kotlin and Java), iOS, Cordova, Flutter, and React Native. You can also access the code after saving.

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

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

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

5. After verifying the feature works as intended with your Test Group, change the Configuration audience to All Users or Target Specific Users and set the percentage and conditions. Manage the Configuration from the Airship dashboard. You can turn it on and off, adjust the audience, update properties, change the schedule, etc. Repeat this step for each Configuration.

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

Use cases and example implementation

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.
• Live updates — Make immediate changes to your app or website by updating property values.
• Holiday Promotions — Create a flag for promotional banners in your app. Using Configurations, launch the banners to 100% of the U.S. audience after Thanksgiving, and to 100% of the E.U. audience in early November. This ensures that each region receives the promotion at the optimal time, maximizing engagement and driving the success of the campaign.
• Retail App Loyalty Program — Create a flag to launch a new loyalty program in your retail app. Release the program to your most loyal users and lowest tier users at different rates, based on observed differences in user behavior for those audiences. You can then create individual Configurations of the Feature Flag for each audience, and roll out the experience to 50% of most loyal users and 10% of lowest tier users under the same flag using different Configurations. You may also use the Feature Flag properties to customize the promotional text for each audience, displaying different messages to each segment.

The following example is for introducing a redesigned Settings screen in a mobile app. To let all new users experience the new Settings screen:

1. Create a Feature Flag with any relevant properties and default values.
2. Create a Configuration with these Audience settings:
   1. Select Target Specific Users.
   2. Set the Configuration audience percentage to 100.
   3. Add the condition New users.
3. In your app code, set the Feature Flag interaction event to occur 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 user that is in the Configuration audiences for the Feature Flag. 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 Configuration audiences for the Feature Flag. 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, increase the audience percentage. Keep adjusting till you reach 100% or the acceptable threshold determined by your planning.

Creating Feature Flags

1. Go to Experiments, then Feature Flags.
2. Select Create Feature Flag.
3. Configure for the flag:

   Field or section	Description	Steps
   Display name	The dashboard label for the flag	Enter text.
   Flag name	The 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.
   Description	Describes what the flag controls	Enter text.
   Properties	Optional. String, number, boolean, or JSON properties that can be used by your app or website code within the Feature Flag. 50 properties maximum.	Select Add property, and then enter a name, select a type, and configure a value. Select Add property for additional properties.

4. Select Save and continue.

Your flag is now saved, and you can create a Configuration at any time.

Creating Configurations

Set up applications for a Feature Flag. If you just created a flag or duplicated a Configuration, start on step 4.

1. Go to Experiments, then Feature Flags.
2. Select a flag’s number of Configurations.
3. Select Create Configuration.
4. Enter for the Configuration:

   Field	Description	Steps
   Display name	The dashboard label for the Configuration	Enter text.
   Description	Describes the purpose of the Configuration	Enter text.

5. Select Properties to continue.
6. (Optional) To override the flag’s property values for this Configuration only, select the plus icon () next a property, then set a new value.
7. Select Audience to continue, then select and configure the audience:

   Option	Description	Steps
   All Users	Makes the feature available to random users for a percentage of your total app or web audience.	Set a percentage.
   Test Users	Makes the feature available to users in a Test Group.	Select a test group.
   Target Specific Users	Makes the feature available to random users for a percentage of your app or website that meet specified 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 above for the list of conditions.

8. Select Schedule to continue, then schedule the period when the Configuration 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.
9. Select Review to continue, then review your Configuration’s settings and copy the code snippets for your developer. The code snippet is the same in all Configurations for a flag, so you only need to provide it to your developer once.
10. Select Launch to make the Configuration active or Exit to save it as a draft. See the status information in Managing Configurations.

Implementing the code

For information about accessing flags in the app SDKs, tracking interaction, and error handling, see Feature Flags in our Mobile platform documentation. For Web implementation, contact Support .

For information about accessing flags in the SDKs, tracking interaction, and error handling, see our platform documentation:

• App Feature Flags
• Web Feature Flags

You can return to the dashboard to get the code snippets at any time:

1. Go to Experiments, then Feature Flags.
2. Select a flag’s number of Configurations.
3. Select the pencil icon () for a Configuration.
4. In the Review step, copy the code snippets.
5. Select Exit.

Using Feature Flags with messaging

You can use a Configuration’s audience as the audience for an In-App AutomationMessages cached on users’ devices and displayed when users meet certain conditions within your app, such as viewing a particular screen or opening the app a certain number of times. or SceneA single or multi-screen in-app experience cached on users’ devices and displayed when users meet certain conditions in your app or website, such as viewing a particular screen or when a Custom Event occurs. They can be presented in fullscreen, modal, or embedded format using the default swipe/click mode or as a Story. Scenes can also contain survey questions.. See the Audience step in each Create guide:

• Create an In-App Automation
• Create a Scene

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 a Feature Flag interaction event occurs. See the Feature Flag Interaction Event trigger in each Triggers guide:

• In-App Experience Triggers
• Sequence Triggers

Example campaign strategy

For feature rollout 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, 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. Your current flags are shown by default. Use the Current/Archived filter to update the list. The default sort order is by last modified, and each row displays:

• Display and flag names
• Description
• Date modified
• Status — Active (has at least one Active or Scheduled Configuration) or Inactive (has Draft or Ended Configurations only)
• Number of Configurations

Manage flags by selecting an icon or link in a flag row:

Editing Flag properties

You can add new properties to a flag at any time. If a flag’s Configurations do not have overrides on a property, you can edit any part of that property at the flag level or remove the property from the flag.

When editing a Feature Flag that has Configurations with property overrides, note the following:

• For Active or Scheduled Configurations with an override on a property, you can edit that property’s default value at the flag level. You cannot delete that property from the flag.
• For Draft Configurations with an override on a property, editing that property’s type at the flag level deletes the overrides in the Draft Configuration.

Whenever you change property names or types at the flag level, you must update the code snippet in your app or website for changes to take effect. You do not need to update the code snippet when changing a flag’s default property values only.

Managing Configurations

To manage Configurations, go to Experiments, then Feature Flags, then select the number of Configurations for a flag. Configurations are listed by status under Active and Scheduled or Ended and Draft.

Active and Scheduled Configurations are listed in priority order, with the following information:

• Priority number
• Status — Active or Scheduled
• Configuration name
• Description
• Audience — “Test group” or percentage
• Start and end dates and times in UTC

For Ended and Draft Configurations, use the Current/Archived filter to update the list. The default sort order is by last modified, and each row displays:

• Configuration name
• Description
• Date modified
• Schedule
• Status — Draft or Ended

Manage Configurations by selecting an icon or link in a flag row. Select the three dots icon () for more. Options:

Viewing reports

Flag usage data is available in the dashboard. See Viewing Feature Flag and Scene Rollout usage.

Accounts with Performance AnalyticsA customizable marketing intelligence tool that provides access to reports and graphs based on engagement data. can view reports and download a list of users who have interacted with the flag:

1. Go to Experiments, then Feature Flags.
2. Select the number of Configurations for a flag.
3. Select the report icon () for a Configuration, then view reports:

   Report	Description	Download steps
   Feature Flag interactions	Counts of users in the Configuration audience with at least one interaction event and interaction events per date. The default view is the last 30 days. Use the date selector to define a different time period.	Select the down arrow icon, select CSV or TEXT format, and then select Download.
   Users in Configuration audience with interaction events	A count of users in the Configuration audience with at least one interaction event. Users are counted as Channel IDsAn Airship-specific unique identifier used to address a channel instance, e.g., a smartphone, web browser, email address.. Selecting the count lists the platform and Named UserA customer-provided identifier used for mapping multiple devices and channels to a specific individual. for each Channel ID.	Select the count to access the list of users. To export the list, select Download. If the count exceeds viewable rows, you can export the full list by selecting Download results to see more.

Contact Airship Sales  to add Performance Analytics to your Airship plan.