How to create my first feature flag?
This guide is designed to help you create and activate Feature flags in your mobile application (Android or iOS) or your website. For each use case, we provide SDKs in the main languages (PHP, Java, Swift, NodeJS..). You can have the complete list of our SDKs and follow the installation guidelines provided for each SDK here.
Creating a new site / property
Before creating any feature flag, you need to create a new site/property in your Kameleoon account. A site can be an environment (production, staging), a website or your mobile application (Android or iOS).
Each site has its own sitecode, which uniquely identifies a site in your Kameleoon account. If you want to run feature flags across several of your applications and websites without having to duplicate them on each site, we recommend you set up only one site and use the same sitecode in all our SDKs.
The sitecode is really important and it will be required in our SDK when you initialize the KameleoonClient object.
NodeJS SDK example
Creating your first feature Flag
On the side menu of the back-office, click on “New project” (or “NEW FEATURE” on the Feature flags dedicated dashboard).
Name your feature flag, provide a unique key (which you will use in our SDKs methods) and choose the site / property on which you would like to activate this feature flag.
To activate your first feature flag, you only need to:
- define the exposition rate: this is the percentage of your users for which you want to activate or roll out your feature flag;
- choose at least a goal/KPI you want to measure in our reporting tool for this feature flag.
Optionally, you can:
- enter a description;
- add tags, which you can use to filter the dashboard list;
- rollout your feature flag to specific groups of users who share common attributes. For this, you will need to define custom data and then build segments by combining custom data with OR/AND operators;
- define feature variables (Number, Boolean, String or JSON) to remotely update the content of your feature flags in production. There is no limitation in the number of feature variables you can create.
Rollout a feature flag to specific group of users
If you want to rollout a feature flag to a group of users, you will need to:
- create custom data;
- set the value of the custom data by using our SDK method addData();
- create a segment by combining several of your custom data.
Create a custom data
On the side menu of the back-office, click on “Targeting → Advanced tools” and then hit the CTA “NEW”. Choose the type of targeting “Custom data” and choose your site/property.
Name your custom data, choose the Acquisition method “Activation API”, the “type” of your custom data (String, Boolean or Number) and the scope “Visit”. Those are the only settings compatible with our feature flag product.
Set the value of the custom data by using our SDK
To associate various custom data with the current user, you need to use the addData() method of our SDK (please read the technical documentation of our SDK). This method has to be called before you activate your feature flag with the method activateFeature().
Note that the addData() method doesn’t return any value and doesn’t interact with the Kameleoon back-end servers by itself. Instead, all declared data is saved for further sending via the flush() method. This reduces the number of server calls made, as data is usually grouped into a single server call triggered by the execution of flush().
See an example of code below: kameleoonClient.addData( visitorCode, new Data.CustomData(31, "Brand name 1") ); kameleoonClient.flush(visitorCode);
Note that you will need to use the unique id of the custom data (in the code above, the ID is 31). It can be found once the custom data has been created by editing it (field: Custom data index).
Create a segment by using your custom data
To create a segment, simply hit the CTA “Create a new segment” from the feature flag configuration page. The segment builder will open and you will be able to use your custom data and set the value(s) you want to target. You can combine several of them with AND/OR operators.
Defining feature variables
Feature variables let you variabilize parts of your feature flag code so that you can dynamically assign values depending on your use case, without having to hard code them in your source code. So, instead of updating your application or website by deploying new code, you can directly update the feature flag remotely by updating the feature flag configuration.
A feature variable can be a number, a boolean, a string or a JSON code. To retrieve a feature variable content, you need to call the obtainFeatureVariable() method of our SDK right after calling the activateFeature() method.
Once you are happy with your configuration, you can click on the CTA “Launch” to activate the feature. Then you will need to use our SDK methods to retrieve the feature flag configuration and activate it from your application or website.
Once your feature flag has been launched / activated, you will need to follow the developer documentation available for each SDK. In a nutshell, you will need to :
- Install the SDK in your app or website. For web SDKs, you will need to provide credentials (client_id and client_secret) via a configuration file available in the SDK, which can also be used to customize the SDK behavior. You can ask your credentials to your Account Manager.
- Initialize the KameleoonClient. Remember: you will need your sitecode here.
- Activate the feature flag by calling the activateFeature() method of our SDK. This method usually takes a visitorCode and the featureKey (the one you have chosen when you have created your feature flag). The activateFeature() method returns a boolean value: true if the user should have this feature or false if not. Kameleoon will randomly expose your visitor to your feature flag (except if you have rolled out it to 100% of your users). If you have set up a segment for your feature flag, Kameleoon will only activate the feature if the user meets the conditions defined in your segment. For mobile SDKs, the initialization of the Kameleoon Client is not immediate, as it needs to perform a server call to retrieve the current configuration for all active feature flags. The runWhenReady() method of the KameleoonClient class allows to pass a callback function that will be executed as soon as the SDK is ready for use. It also allows the use of a timeout. Two methods must be implemented: onReady() and onTimeout(). The onReady() method will be called once the Kameleoon client is ready, and should contain the code that activates your feature flag. The onTimeout() method will be called if the specified timeout happens before the client is initialized.
- (Optional) Retrieve the feature variables associated with your feature flag by calling the obtainFeatureVariable() method of our SDK. This method takes two input parameters: your feature Key and your variable Key. It will return the data as a java.lang.Object instance. Usually it should be casted to the expected type (the one defined on the web interface).
- (Required if you use a segment in your feature flag) You can associate data with the current user. For this, you need to use the addData() method of our SDK. Data associated with the current user via this method is not sent immediately to our servers. It is stored and accumulated until it is sent automatically by the activateFeature() or trackConversion() methods, or manually by the flush() method. This allows you to control exactly when the data is flushed to our servers.
- Track metrics to measure the success of your feature flag. You need to use the trackConversion() method. This method requires a visitorCode and a goal ID to track conversion on this particular goal. In addition, this method also accepts revenue as a third optional argument to track revenue. Only custom goals can be tracked in feature flags reports. The ID you need to use in the trackConversion() method is available in the custom goal creation popin.