experimentation-sdk v0.0.9

experimentation-SDK

experimentation-sdk is a library that provides multiple implementations of our feature flag & experimentation service. Internally, it utilizes Split.io for feature flagging and experimentation. This library allows you to proxy different experimentation requests seamlessly and without worrying about how we are getting them.

Features

• Multiple experimentation service implementations - Microservice front ends, node backend, php backend, go backend,
• Utilizes Split for robust and scalable feature flagging.
• Simple API for interacting with experiments and feature flags.
• Extendable and customizable for various experimentation strategies.

Installation

Install the package via npm: npm install @fieldnation/experimentation-sdk

Usage

import useTreatments from '@/hooks/use-treatments';

const Component = Props => {
    const { theTreatmentFor } = useTreatments();

    // theTreatmentFor returns an object where you can check either .isOn or .isOff based on your needs

    if ( theTreatmentFor('MATCH_ALPHA').isOn ) {
        return <div />
    } else if ( theTreatmentFor('MATCH_BETA').isOff ) {
        return <span />
    } else {
        return <control />
    }
}

For type safety all available treatments are exported as constants and enforced as a function paramater

import { TreatmentTypes } from '@/utils/constants';

theTreatmentFor(TreatmentTypes.MATCH_ALPHA).isOff

// for debugging or if you need to know whether a user is in a treatment group but not "on/active"
// you can use the .exists property

if (theTreatmentFor(TreatmentTypes.MATCH_GAMMA).exists) {
    // in control - do something
}

Setting up a new feature flag

First you need to request access to our split.io account. Then you need to create the feature flag in split:

1. Go to "feature flags" tab & click "new feature flag"
2. Name the new flag - our convention for UI flags is to use constant case (eg. FEATURE_FLAG), set traffic type, add tags & desc
3. Click "create". Now you need to set it up.
4. You will see the new flag selected along with 2 environments, make sure you have the "staging" env selected and click "initiate environment"
5. IMPORTANT: make sure you click the "flag sets" button next to "review changes" and set it as "frontend"
6. Under "targeting rules" make sure "serve" is the selected option with whatever value you want to be on
7. Click "review changes" and you can look at a diff of everything that will take affect. Hit save.
8. Update "TreatmentTypes" in "@/utils/constants"

Now you will be able to check for this flag from your consuming code. Rollouts for this are also extremely fast because our client side SDK continually polls the server for updates, only requesting delta changes once initialized resulting in extremely small payload sizes. This also enables the ability of the "kill" button on flags if something goes wrong

Keep in mind that the split staging env controls every FN dev env including UAT, so to test and verify functionality of new code you can turn the flag on in the "staging" env without affecting prod, and then when you are ready to turn it on in prod you can initiate that env for the flag as well. This also allows us to test new targeting rules & treatment variants in the future with very little risk.

Release Process

The release process is continuous (CI/CD).

1. In github, make a PR from your feature branch to the main branch
2. Add either the patch, minor, or major label to your PR using the following guideline:
   • If this is a bug fix select patch
   • If your branch introduces a new feature select minor
   • If your branch introduces any potentially breaking changes select major
3. Follow the CR process and have at least one BMX team member approve your PR
4. Merge your PR to main

On merge to main, the CI process will automatically:

• Build the package into both ESM & CJS bundles with vite
• Auto will increment the NPM package version along with updating the release notes
• A new NPM package will be published at @fieldnation/experimentation-sdk@latest

Changelog

View the changelog here