Upsight logo Back to top

Managed Variables

Defining Managed Variables


To begin, you must create a JSON file in a raw folder in your application's res folder. Name the JSON file uxm_schema.json with a structure as indicated in the following section:

[
  {
    "tag": "enable_extended_mode",
    "description": "Flag which allows to enable extended mode",
    "type": "boolean",
    "default": true
  },
  {
    "tag": "personage_name",
    "description": "Default name for personage",
    "type": "string",
    "default": "Bob"
  },
  {
    "tag": "personage_coins",
    "description": "Number of coins available for personage",
    "type": "integer",
    "default": 2000,
    "min": 0,
    "max": 10000
  },
  {
    "tag": "personage_strength",
    "description": "Default strength for personage",
    "type": "float",
    "default": 0.5,
    "min": 0,
    "max": 1
  }
]

As above, this file will contain an array of JSON objects with the following keys:

  • default: the default value of a variable. Can be of type string, integer, float, or boolean.
  • description - A description of what the variable is to be used for.
  • tag - The string by which you will reference the variable in your code.
  • type - The type of the variable as it will be indicated on the Upsight Dashboard. Valid values are the strings string, boolean, integer, and float.
  • min - The minimum value this integer or float variable can have.
  • max - The maximum value this integer or float variable can have.

Accessing Managed Variables


Once your variables are declared, you can then access them from your code by calling one of the below UpsightManagedVariable methods based on the type of variable you have stored:

  • UpsightManagedString.fetch(UpsightContext upsight, String tag);
  • UpsightManagedInt.fetch(UpsightContext upsight, String tag);
  • UpsightManagedFloat.fetch(UpsightContext upsight, String tag);
  • UpsightManagedBoolean.fetch(UpsightContext upsight, String tag);

The returned object will have a get method appropriate to its type which gives you the most recent value returned from the server. See below for a full code example:

String tag = "personage_name";
UpsightManagedString managedPersonageName = UpsightManagedString.fetch(mUpsight, tag);
Log.d(LOG_TAG, managedPersonageName.get());

The above fetch APIs return an UpsightManagedVariable synchronously, which means they will block on a database read and should not be called from the main thread. To perform asynchronous reads you can use the following methods:

  • UpsightManagedString.fetch(UpsightContext upsight, String tag, Listener<UpsightManagedString> listener);
  • UpsightManagedInt.fetch(UpsightContext upsight, String tag, Listener<UpsightManagedInt> listener);
  • UpsightManagedFloat.fetch(UpsightContext upsight, String tag, Listener<UpsightManagedFloat> listener);
  • UpsightManagedBoolean.fetch(UpsightContext upsight, String tag, Listener<UpsightManagedBoolean> listener);

In either case, after you retrieve the UpsightManagedVariable object, calling get() on that object will get you the most updated value synchronously. See below for a code example:

String tag = "personage_name";
UpsightManagedString.fetch(mUpsight, tag, new UpsightManagedVariable.Listener<UpsightManagedString>() {
    @Override
    public void onSuccess(UpsightManagedString managedPersonageName) {
        Log.d(LOG_TAG, managedPersonageName.get());
    }

    @Override
    public void onFailure(UpsightException e) {
        Log.e(LOG_TAG, e.getMessage());
    }
});

The UpsightManagedVariable objects also implement java.util.Observable, so you may subscribe to them to be notified of when the underlying value is updated. The following example adds a java.util.Observer to the synchronous fetch call.

String tag = "personage_name";
final UpsightManagedString managedPersonageName = UpsightManagedString.fetch(mUpsight, tag);
managedPersonageName.addObserver(new Observer() {
    @Override
    public void update(Observable observable, Object data) {
        Log.d(LOG_TAG, managedPersonageName.get());
    }
});

The following examples adds a java.util.Observer to the asynchronous fetch call.

String tag = "personage_name";
UpsightManagedString.fetch(mUpsight, tag, new UpsightManagedVariable.Listener<UpsightManagedString>() {
    @Override
    public void onSuccess(final UpsightManagedString managedPersonageName) {
        managedPersonageName.addObserver(new Observer() {
            @Override
            public void update(Observable observable, Object data) {
                Log.d(LOG_TAG, managedPersonageName.get());
            }
        });
    }

    @Override
    public void onFailure(UpsightException e) {
        Log.e(LOG_TAG, e.getMessage());
    }
});

Managed Variable Callback Handler


By default, the SDK will update the managed variable values whenever the server sends updates, but you may wish to observe when synchronization is complete, or skip updates during times when you need the managed variable values to be stable. You can hook into the synchronization flow by registering a UpsightUserExperience.Handler in your UpsightSessionCallbacks.onStart():

public class MySessionCallbacks implements UpsightSessionCallbacks {

    @Override
    public void onStart(final UpsightSessionContext upsight, final UpsightSessionInfo previousSessionInfo) {
        // Register handler for user experience bundles.
        UpsightUserExperience.registerHandler(upsight, new UpsightUserExperience.Handler() {

            @Override
            public boolean onReceive() {
                // Implement logic to decide whether to apply managed variable changes.
                // This will execute whenever a new user experience bundle arrives. 
                return true;
            }

            @Override
            public void onSynchronize(List<String> tags) {
                // If onReceive() returned true, this callback ensures all managed variables are
                // now synchronized with the server. If the new user experience bundle is
                // skipped with onReceive() returning false, the managed variable values will
                // still hold the last-known local values.
            }
        });
    }

    @Override
    public void onStarted(final UpsightContext upsight) {
        // Do nothing.
    }

    @Override
    public void onResume(final UpsightSessionContext upsight, final UpsightSessionInfo resumedSessionInfo) {
        // Do nothing.
    }

    @Override
    public void onResumed(final UpsightContext upsight) {
        // Do nothing.
    }
}

Warning The application will not receive UpsightUserExperience.Handler callbacks if the device has no network connectivity.