.. _ab_testing:

A/B Testing
===========

Titan SDK integrates with Scopely's A/B testing solution. It allows you retrieve
a dictionary of values for the A/B variants the device is enrolled in:

.. code-block:: java

    AbTesting abTesting = AbTesting.getInstance();
    // This runs networking code on the calling thread so it must not be
    // called from the UI-Thread or it will throw an exception at your face
    Map<String, String> dict = abTesting.getEnrollmentsValues();

    String labelMsg = dict.get("label_msg");

This can be done asynchronously too:

.. code-block:: java

    AbTesting abTesting = AbTesting.getInstance();
    abTesting.getEnrollmentsValues(new AbTestValuesListener() {

      @Override public void onValuesReceived(Map<String, String> values) {
        String labelMsg = values.getStringOr("label_msg");
      }

      @Override public void onError(String message) {
        // something wrong happened
      }
    });

.. Warning:: You must have initialized Titan SDK before you can use ``AbTesting.getInstance()`` (see :ref:`setup`)
  otherwise an ``IllegalStateException`` will be thrown.


``getEnrollmentsValues()`` **should be called only once**. The values retrieved are cached
and you can access them using ``getValue`` or ``getValueOr``:

.. code-block:: java

    String labelMsg = abTesting.getValueOr("label_msg", "Default message")

Even if ``getEnrollmentsValues()`` fails due to connectivity problems, ``getValue`` can still be used and will return
valid values (from the cache).

Example
=======

If you want to get started with A/B testing there's an dummy experiment ready to be used. In order to
use it you must setup the SDK with this API key: `00000000-0000-0000-0000-000000000000`. This experiment
targets Android and iOS users, and it has two variables: `hello_msg` and `other_variable` which will change
depending on which variant the phone got enrolled in.

You can download a full example (Titan SDK + A/B Testing) `from here <http://scopely.github.io/titan-android/titan-sdk-example.zip>`_.