Add initial support for experimentation platform

[renanferrari]

This PR adds an initial support for the Experimentation Platform API (internal ref: pbmo2S-yK-p2).

Usage

The main class added by this PR is the ExperimentStore, to which a client implementation would interact in the following way:

First, it would fetch the latest experiment assignments for an user by calling experimentStore::fetchAssignments:

val payload = FetchAssignmentsPayload(Platform.WORDPRESS_ANDROID)
experimentStore.fetchAssignments(payload)

And then handle the resulting OnAssignmentsFetched:

fun onAssignmentsFetched(result: OnAssignmentsFetched) {
    if (!result.isError) {
        val assignments = event.assignments
        // Handle assignments
    } else {
        // Handle error
    }
}

Once the assignments are fetched, they are automatically cached and can be retrieved like so:

val assignments = experimentStore.getCachedAssignments()

With an Assignments object in hand, it's possible to retrieve a Variation for a specific experiment and then handle it accordingly:

when (val variation = assignments.getVariationForExperiment("my_experiment")) {
    is Control -> handleControl() // Show control option
    is Treatment -> handleTreatment() // Show treatment option
    is Unknown -> handleUnknown() // Experiment doesn't exist or wasn't retrieved
    is Other -> when (variation.name) { // Any other value
        "other_value_one" -> handleValueOne()
        "other_value_two" -> handleValueTwo()
        else -> handleUnknown()
    }
}

It's also possible to check if we should fetch newer assignments:

if (assignments.isStale()) {
    // TTL has expired, we should fetch newer assignments for this user
}

Next steps

Theoretically, this implementation already gives us the ability to use the Experimentation Platform API in our apps, although we still need to wait for the apps to be officially supported by the platform (more information about this in the internal reference linked above).

From a practical perspective however, we should probably still add a middle abstraction between the clients and this implementation to make it a little bit easier to do stuff like generating and storing anonymous IDs and automatically fetching new values when the cached results are stale, etc.

The way I see it, the most obvious candidates to receive such implementation would be either WordPress-Analytics-Android, a brand new library, or even the apps themselves if we don't care much about sharing that logic.

This is totally open for discussion.

To test

You can either run the included unit tests or use the following steps on the example app:

1. On the initial screen, tap Experiments.
2. On the next screen, select a platform to query (keep in mind the only platforms officially supported at the moment are calypso and wpcom).
3. Optionally, you can add or generate an Anonymous ID to be included in the request as well.
4. Tap Fetch Assignments.
5. Check the results printed by the in-app console.
6. Tap Get Cached Assignments.
7. Verify that the returned results match the ones fetched before.

Feel free to try out different combinations, both signed in and signed out.

[planarvoid]

hey @renanferrari , I was wondering why you used event bus instead of the newer approach with coroutines (FluxC wiki). I think we shouldn't be using EventBus for new stores.

[renanferrari]

@planarvoid This is the first time I've created a store and I actually wasn't aware we shouldn't be using EventBus for new ones. It makes total sense! I've now made the coroutine function public so the client can call that directly.

[planarvoid]

I think I'd just remove this function and the Store parent unless you really need the reason for the event bus usage (it should be pretty rare - mostly for things consumed already by multiple places in the app).

[planarvoid]

do you think you could wrap this in coroutineEngine.withDefaultContext in order to add some logging to the method call?

[planarvoid]

The store looks great! I have two minor comments 👍 Thanks for the changes from event bus to coroutines 👍

[renanferrari]

Hey @planarvoid, I just realized I never pinged you back to let you know this is ready for another round of review.

[planarvoid]

Thanks for the ping and the changes @renanferrari , it's looking good 👍

[withinboredom]

I haven't finished reviewing this code, but the assignment will be null if it's "control" and the control's name will never be sent back in an API response. This is so an old client is guaranteed to handle a disabled experiment properly or in the event an experiment needs to be disabled in an emergency, it will revert back to the control.

[withinboredom]

Instead of returning Unknown, consider returning Control if the experiment isn't found. This way old clients will properly handle a disabled experiment which are not returned via the API response, or in the case a client is released before the experiment goes live.

[renanferrari]

Thanks for your comments, @withinboredom! I'll make sure to address them in a future PR soon, since this one has already been merged.