Skip to content

Reference implementation that demonstrates core Proctor functionality

License

Notifications You must be signed in to change notification settings

indeedeng/proctor-demo

Repository files navigation

Proctor Demo and Reference Implementation

Lifecycle

This project is a reference implementation and demonstration of Proctor, a Java-based A/B testing framework by Indeed. It is a simple Spring MVC webapp that uses Proctor to determine what background color to set for a web application.

For more information, see the Proctor documentation. The Quick Start document is a good guide to understanding the code in this reference implementation.

Demo Online

The demo is (usually) running at proctordemo.site. It loads its test definitions from JSON files that can be at any URL. The examples below are self-hosted within the demo app itself. A URL parameter allows you to change the definition file.

Things to Try

  1. Testing two colors at 25% and 25%: link. Click "Show Details" and "Reset" to change your user ID and (possibly) be put in a different test bucket.

  2. Testing the same two colors at 50% and 50%: link

  3. Going to 100% for one color: link

  4. Using prforceGroups to see a different test group, regardless of allocations: link

  5. Reset to discard the forced group in the previous step: link

  6. Basing color on Android vs. iOS user agent instead of random allocation: link. If you're not on Android or iOS you won't see a background color.

Web-Based Remote Service API

An additional endpoint /rpc is provided in this implementation as an example of how you might implement group selection as a remote service. To use this endpoint, you must provide as least the uid (user ID) and agent (user agent) query parameters. It does not use any cookies or HTTP headers directly. It supports these parameters:

Parameter Description Required? Example
uid User ID for USER-based tests (can be any string) Yes 8ac65ba448be45afb86706e8cab979cf
agent User Agent (equivalent to User-Agent HTTP header) Yes (may be blank) Mozilla/5.0
defn Definition URL No (uses default if not provided) /defn/example.json

Building and Running Demo Locally

  1. mvn clean package && java -jar target/dependency/webapp-runner.jar target/*.war

  2. Go to http://localhost:8080/

To run on a different port locally, use the --port option for webapp-runner. For example, to run on port 9999:

java -jar target/dependency/webapp-runner.jar --port 9999 target/*.war

The Source

The JSON specification that is enumerates the test and its buckets. This is used to generate convenience classes at compile time and to load the test matrix at runtime.

Helper component that manages loading and caching the test matrix from a definition file at a remote URL.

Spring controller that handles assigning a UUID cookie to identify the user and calling into proctor to get the groups for the current user. Also provides /rpc service endpoint support.

Java Servlet Page view for the demo controller; renders the test behavior and some controls to interact with the demo.

A helper class based partially on bitwalker's UserAgentUtils that can be a useful context parameter for proctor.

Code of Conduct

This project is governed by the Contributor Covenant v 1.4.1

License

Apache License Version 2.0

About

Reference implementation that demonstrates core Proctor functionality

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published