Update docs

docs: Added badges to indicate various package status docs: Added missing docs for `react-ab-testing` and `py-ab-testing`, so the `NPM` and `PYPI` web interface will show proper descriptions.
appannie · Mar 16, 2020 · 245955b · 245955b
1 parent 23ca5d9
commit 245955b
Show file tree

Hide file tree

Showing 4 changed files with 172 additions and 2 deletions.
diff --git a/README.md b/README.md
@@ -1,17 +1,48 @@
 # AB Testing
 
-AB testing library supporting multi-variance testing with a deterministic algorithm not requiring any complex backend or database.
+![CI](https://github.com/appannie/ab-testing/workflows/CI/badge.svg)
+[![Coverage Status](https://coveralls.io/repos/github/appannie/ab-testing/badge.svg)](https://coveralls.io/github/appannie/ab-testing)
+![GitHub Release Date](https://img.shields.io/github/release-date/appannie/ab-testing)
+
+AB testing library supporting multi-variance testing with a deterministic algorithm not requiring any complex backend or database. Supporting both Javascript and Python.
 
 The segmentation logic is maintained in the AB testing client and based itself on a centralized configuration. The cohort assignment logic is deterministic and follows a simple hash pattern based on the `crc32c` algorithm (`crc32c(userId, crc32c(experimentName)) % 100`)
 
+# Packages
+
+| Package                            | Status                                                                                                                                                                                                                                                                | Description                                                                                     | API Doc                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------------------------- |
+| `@appannie/ab-testing`             | ![npm (scoped)](https://img.shields.io/npm/v/@appannie/ab-testing) <br> ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@appannie/ab-testing) <br> ![npm](https://img.shields.io/npm/dw/@appannie/ab-testing)                                     | Core package implementing ab-testing SDK APIs.                                                  | [README.md](./packages/ab-testing/README.md)             |
+| `@appannie/react-ab-testing`       | ![npm (scoped)](https://img.shields.io/npm/v/@appannie/react-ab-testing) <br> ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@appannie/react-ab-testing) <br> ![npm](https://img.shields.io/npm/dw/@appannie/react-ab-testing)                   | React binding for the `@appannie/ab-testing` package.                                           | [README.md](./packages/react-ab-testing/README.md)       |
+| `@appannie/ab-testing-hash-object` | ![npm (scoped)](https://img.shields.io/npm/v/@appannie/ab-testing-hash-object) <br> ![npm bundle size (scoped)](https://img.shields.io/bundlephobia/min/@appannie/ab-testing-hash-object) <br> ![npm](https://img.shields.io/npm/dw/@appannie/ab-testing-hash-object) | An helper library that simplify helps protecting private information like PIIs.                 | [README.md](./packages/ab-testing-hash-object/README.md) |
+| `py-ab-testing`                    | ![PyPI](https://img.shields.io/pypi/v/py-ab-testing) <br> ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/py-ab-testing) <br> ![PyPI - Downloads](https://img.shields.io/pypi/dw/py-ab-testing)                                                       | Python implementation of APIs in `@appannie/ab-testing` and `@appannie/ab-testing-hash-object`. | [README.md](./packages/py-ab-testing/README.md)          |
+
 # Installation
 
+## React App
+
 ```sh
 npm install @appannie/react-ab-testing
 # or
 yarn add @appannie/react-ab-testing
 ```
 
+## Vanilla Javascript
+
+```sh
+npm install @appannie/ab-testing
+# or
+yarn add @appannie/ab-testing
+```
+
+## Python
+
+```sh
+pip install py-ab-testing
+# or
+pipenv install py-ab-testing
+```
+
 Note that a [raw JS version is also available (`@appannie/ab-testing`)](./packages/ab-testing/README.md). Feel free to write your own adapters for other framework.
 
 # Setup with React

diff --git a/packages/ab-testing-hash-object/README.md b/packages/ab-testing-hash-object/README.md
@@ -1,4 +1,4 @@
-# Hash object
+# AB Testing Hash Object
 
 Utility to hash common objects used within the ab-testing framework (user profile and the configuration `force_include` section.)
 

diff --git a/packages/py-ab-testing/README.md b/packages/py-ab-testing/README.md
@@ -0,0 +1,74 @@
+# Py AB Testing
+
+AB testing library supporting multi-variance testing with a deterministic algorithm not requiring any complex backend or database.
+
+The segmentation logic is maintained in the AB testing client and based itself on a centralized configuration. The cohort assignment logic is deterministic and follows a simple hash pattern based on the `crc32c` algorithm (`crc32c(userId, crc32c(experimentName)) % 100`)
+
+# Installation
+
+```sh
+pip install py-ab-testing
+# or
+pipenv install py-ab-testing
+```
+
+# Usage
+
+Note: The `config` variable holds an `dict` with [configuration file format that documented here](../../README.md).
+
+```python
+from ABTesting import ABTestingController
+
+user_profile = {
+    'persona': user.persona,
+    'employee': user.isEmployee,
+}
+
+controller = ABTestingController(config, user.id, user_profile)
+cohort = controller.get_cohort('experiment-name')
+
+if cohort == 'blue':
+    do_something()
+elif cohort == 'red':
+    do_something_else()
+else:
+    do_default_behavior()
+```
+
+# Protecting Private Information
+
+Similar to the Javascript SDKs, the package comes with an optional util for hashing private information with `sha256`.
+
+## Prepare config file BEFORE make it public
+
+```python
+from ABTesting.utils import hash_dict
+
+config['salt'] = salt
+for experiment in config['experiments']:
+    for cohort in experiment['cohorts']:
+        cohort['force_include'] = hash_dict(cohort['force_include'], salt)
+```
+
+## In runtime
+
+```python
+from ABTesting.utils import hash_dict
+
+hashed_user_profile = hash_dict(
+    {
+        'persona': user.persona,
+        'employee': user.isEmployee,
+    },
+    salt
+)
+
+# Make sure config is hashed with the same salt
+controller = ABTestingController(config, user.id, hashed_user_profile)
+```
+
+# Credits
+
+Made with ❤️ by [Zhang Tao](https://github.com/BananaWanted) and [Simon Boudrias](https://github.com/SBoudrias) from the App Annie Beijing office.
+
+Available for public use under the MIT license.
diff --git a/packages/react-ab-testing/README.md b/packages/react-ab-testing/README.md
@@ -0,0 +1,65 @@
+# React AB Testing
+
+# Installation
+
+```sh
+npm install @appannie/react-ab-testing
+# or
+yarn add @appannie/react-ab-testing
+```
+
+# Getting Started
+
+Wrap your app with the `ABTestingController`
+
+```js
+import { ABTestingController } from '@appannie/react-ab-testing';
+
+const MyApp = ({ user }) => {
+    const profile = {
+        persona: user.persona,
+        employee: user.isEmployee,
+    };
+
+    return (
+        <ABTestingController config={testConfig} userId={user.id} userProfile={profile}>
+            <App />
+        </ABTestingController>
+    );
+};
+```
+
+The required props are:
+
+1. `config`: the configuration object.
+2. `userId`: a unique identifier for your current user. This ID should be the same across visits to make sure your user always end up in the same cohorts. It can a `string` or a `number`.
+3. `userProfile`: a key/value map used to force include a user in given cohorts.
+
+Then within your app, check the cohort a user is assigned to using the `useCohortOf` hook.
+
+```js
+import { useCohortOf } from '@appannie/react-ab-testing';
+
+const Component = () => {
+    const cohort = useCohortOf('experiment-name');
+
+    switch (cohort) {
+        case 'blue':
+            return <BlueButton />;
+        case 'red':
+            return <RedButton />;
+        // 'control' is the default cohort. All experiments have a control cohort.
+        case 'control':
+        default:
+            return <Default />;
+    }
+};
+```
+
+Note: The [configuration file format is documented here](../../README.md).
+
+# Credits
+
+Made with ❤️ by [Zhang Tao](https://github.com/BananaWanted) and [Simon Boudrias](https://github.com/SBoudrias) from the App Annie Beijing office.
+
+Available for public use under the MIT license.