Darwin

Our shiny new AB testing tool! :monkey:

yarn add @kiwicom/darwin

API

Download the test configuration file. On a request take:

• the config object
• request's userAgent
• request's language code in ISO 639-1 with the country postfix — xx-XX
• some salt — usually user's ID

Config

The configuration object is either a JSON file or a JS object with the following structure:

// A single AB test
export type Test = {
  name: string;  // The test's name
  value: string; // The value string
};

// One of AB test's treatment group configurations
export type Value = {
  value: string;  // The treatment group name
  weight: number; // The relative traffic size of the treatment group
};

// Traffic group configuration
export type Traffic = {
  userAgent?: string | null;    // Pattern against which to compare the user-agent
  languages?: string[] | null;  // List of accpeted languages
  affiliates?: string[] | null; // List of accepted affiliates
};

// Configuration of an AB test
export type TestConfig = {
  name: string;    // The AB test name
  values: Value[]; // List of treatment group configurations
};

// Population group with an assigned AB test, or `null` for placeholder slot
export type Group = {
  traffic?: Traffic; // The group's traffic configuration
  test: TestConfig;  // The test configuration for this population group
  enabled: boolean;  // Whether this group is enabled or not
};

// Feature configuration
export type Feature = {
  traffic?: Traffic; // The feature's traffic configuration
  name: string;      // The feature's name
  enabled: boolean;  // Flag indicating whether the feature is enabled or not
};

// A record of enabled/disabled features
export type Features = Record<string, boolean>;

// The root configuration object
export type Config = {
  features?: Feature[];      // The feature configuration
  groups?: Group[]; // Population group configurations
  winners?: Test[];          // Winning tests and their values
};

An example Traffic object containing the English and Russian language, and is iPhone only, for shrek and donkey affiliates:

{
  "languages": ["en-US", "ru-RU"],
  "userAgent": "iPhone",
  "affiliates": ["shrek", "donkey"]
}

The language list is the 639-1 column here. Be sure to include the -XX country postfix, as Kiwi.com recognizes different countries' language variants.

For user agents, see this website. Pick a chunk of the user agent you want and put it in the userAgent field in the traffic object, like in the example.

getTest

Feed the config object function together with the userAgent, language, affiliate and the salt:

import { Config, Test, getTest } from "@kiwicom/darwin";
import { Cookies } from "@kiwicom/cookies";

const config: Config = {/* ... */};

// Returns either a `Test` object, or `null` for no active test
const test: Test | null = getTest({
  config,
  userAgent: req.headers["User-Agent"], // optional
  language: "en-GB", // optional
  affiliate: "shrek", // optional
  salt: "some-user-id-string", // length at least 10 for optimal results
  savedTest: req.cookies[Cookies.DARWIN_TEST], // optional, saved test for the user
});

// optionally, save/remove test name from storage
if (test === null) {
  // remove `test.name` from e.g. cookies
} else {
  // save `test.name` to e.g. cookies
}

This object has no functions and thus is serializable — send it to the client encoded as JSON.

getFeatures

Feed the config object function, optionally together with the userAgent, language and affiliate:

import { Config, Features, getFeatures } from "@kiwicom/darwin";

const config: Config = {/* ... */};

const features: Features = getFeatures({
  config,
  userAgent: req.headers["User-Agent"], // optional
  language: "en-GB", // optional
  affiliate: "shrek", // optional
});

This object has no functions and thus is serializable — send it to the client encoded as JSON.

DarwinProvider

Server:

Use the test object in your provider:

import { DarwinProvider } from "@kiwicom/darwin";

// ...
return ReactDOMServer.renderToString(
  <DarwinProvider
    test={test}
    features={features}
    winners={winners}
  >
    <Root />
  </DarwinProvider>
);

Client:

Take the test and features sent from the server and feed it to the provider.

Avoid sending the whole downloaded configuration file to the client to save bundle size and avoid leaking test information.

import { DarwinProvider } from "@kiwicom/darwin";

import { handleLogDarwin } from "src/logger";

const { test, features, winners } = window.__DARWIN__;

// ...
ReactDOM.hydrate(
  <DarwinProvider
    test={test}
    features={features}
    winners={winners}
    onTest={handleLogDarwin}
  >
    <Root />
  </DarwinProvider>,
  document.getElementById("root"),
);

useTest hook

Checks if the queried test is running and returns its value, null for reference group.

It also saves the queried test to session data if it returned a non-null result.

import { useTest } from "@kiwicom/darwin";

const version = useTest("valdoge");
if (version === "g") {
  // ...
}

You can then retrieve the session data with loadSession;

useFeature hook

Tells you if a feature is on / off.

import { useFeature } from "@kiwicom/darwin";

const hasNavbar = useFeature("navbar");

loadSession

Loads the session test data:

• type Test if a test is active
• null if a test is not present

Only use on the client!

Useful mainly for logging.

The Test type field value is:

• one of test's values for a treatment group
• null for the control group

import { loadSession } from "@kiwicom/darwin";

logger.log("Stuff has happened", {
  ab: loadSession(),
});

Testing

Use the @kiwicom/darwin/mock module for testing purposes.

mockFormat

Appends the URL with specified testing parameters and returns the formatted URL search:

import { mockFormat } from "@kiwicom/darwin/mock";

window.location.search = mockFormat("yolotest", "B");

Takes an optional third parameter as the current URL search that defaults to window.location.search.

mockRetrieve

Retrieves the mock test from the URL search. Consume it before determining an actual test:

import { mockRetrieve } from "@kiwicom/darwin/mock";

const test = mockRetrieve(url.search) ?? getTest({ /* ... */ });

mockFeatureFormat

Appends the URL with specified features and returns the formatted URL search:

import { mockFeatureFormat } from "@kiwicom/darwin/mock";

window.location.search = mockFeatureFormat({ navbar: true, footer: false });

Takes an optional second parameter as the current URL search that defaults to window.location.search.

mockFeatureRetrieve

Retrieves the mock features from the URL search. Merge the mock feature set with features from the config object:

import { mockFeatureRetrieve } from "@kiwicom/darwin/mock";

const features = {
  ...getFeatures({ /* ... */ }),
  ...mockFeatureRetrieve(url.search),
};

mockWinnersFormat

Appends the URL with specified test winners and returns the formatted URL search:

import { mockWinnersFormat } from "@kiwicom/darwin/mock";

window.location.search = mockWinnersFormat([{ name: "test", value: "off" }]);

Note that the function uses __ for grouping test name and value. Please avoid using double-underscore in test names or values!

Takes an optional second parameter as the current URL search that defaults to window.location.search.

mockWinnersRetrieve

Retrieves the mock test winners from the URL search. Merge the test winners set with winners from the config object:

import { mockWinnersRetrieve } from "@kiwicom/darwin/mock";

const winners = {
  ...config.winners,
  ...mockWinnersRetrieve(url.search),
};

Development

Clone and yarn.

Commits

Follow @commitlint/conventional with a mandatory scope of:

• dev for non-production things like CI or tests
• types for adjusting .js.flow files or type signatures
• src for library changes, features, patches...

Examples:

• docs(dev): document commits
• feat(src): add new hook
• chore(types): new spread syntax

Release

• yarn release
• yarn publish

License

MIT