With the Leanplum SDK, you can create variables on your client that take on new values from the server. Using variables in the Leanplum dashboard allows you to roll out changes without having to push an update through the App Store or Google Play. These can also be used in A/B tests to test features for only a percentage of your users.

When you define a variable, you can do so either via our API with setVars or with the platform specific call in our SDK. When you define a variable in your code, it will appear in the Variables tab in Leanplum the next time your app starts in development mode and you sync the client.

Once you are ready to use the Variable value, the value data will be downloaded asynchronously upon the call of Leanplum.start().

Within the Leanplum variables we support many different types. For each variable type we support and examples you can use, see below.

🚧
Using Callbacks and Mid-Session syncs
If you need to use a variable when the app starts or if you need to use a different Variable value for any reason for the user mid-session, we have created a mid-session sync and callbacks that make sure you are using the correct value.
See more on that at Syncing Mid-Session and variable callbacks.

Types

Currently Leanplum variables support the below variable types. We have included a variable example of each type below.

String
Float
Boolean
Dictionary
Array
Leanplum Assets
Color

String

//Define the variable and set the name and value using the Var class. To access the value in your code, use stringValue.

var startLabel = Var(name: "startLabel", string: "Start") // Label of the "Start" button
...
Leanplum.onVariablesChanged {
  let startButton: UIButton = UIButton()
  startButton.setTitle(startLabel.stringValue, for: .normal)
  self.view.addSubview(startButton)
}

//Set the value with the macro DEFINE_VAR_STRING. To access the value in your code, use the stringValue method.

DEFINE_VAR_STRING(startLabel, @"Start");  // Label of the "Start" button.
...
[Leanplum onVariablesChanged:^() {
  UIButton* startButton = [[UIButton alloc] init];
  startButton.text = startLabel.stringValue;
  [self.view addSubview:startButton];
}];

// The variable startLabel will show up on our dashboard within the group "mainScreen".
@Variable(group="mainScreen") public static String startLabel = "Start";  // Label of the "Start" button.

// Use "." to nest groups. You can also use "." with the "name" argument.
@Variable(group="screens.mainScreen") public static String startLabel = "Start";  // Label of the "Start" button.

String
Var<string> startLabel = Var<string>.Define("startLabel", "Start");  // Label for "Start" button.
...
void CreateStartButton() {
  AddButtonWithText(startLabel.Value);
}

Float

//Define the variable and set the name and value using the Var class. 
//To access the value in your code, use the floatValue method.

var shootSpeed = Var(name: "shootSpeed", float: 1.0) // How fast your ship shoots.
...
Leanplum.onVariablesChanged {
  // Move ship according to its speed.
  myShip.moveWithSpeed(shootSpeed.floatValue())
}

//Set the value with the macro DEFINE_VAR_FLOAT. To access the value in your code, use the floatValue method.

DEFINE_VAR_FLOAT(shootSpeed, 1.0);  // How fast your ship shoots.
...
[Leanplum onVariablesChanged:^() {
  // Move ship according to its speed.
  [myShip moveWithSpeed:shootSpeed.floatValue];
}];

@Variable public static float shootSpeed = 1;  // How fast your ship shoots.

Var<float> shootSpeed = Var<float>.Define("shootSpeed", 1.0);  // How fast your ship shoots.
...
void MoveShip() {
    MoveWithSpeed(shootSpeed.Value);
}

Boolean

//Define the variable and set the name and value using the Var class. To access the value in your code, use the boolValue method.

var showAds = Var(name: "showAds", boolean: false) // Whether or not to show ads in the app.
...
Leanplum.onVariablesChanged {
  if showAds.boolValue() {
    self.view.addSubview(adView)
  }
}

//Set the value with the macro DEFINE_VAR_BOOL. To access the value in your code, use the boolValue method.

DEFINE_VAR_BOOL(showAds, false);  // Whether or not to show ads in the app.
...
[Leanplum onVariablesChanged:^() {
  if (showAds.boolValue) {
    [self.view addSubview:adView];
  }
}];

// The variable showAds will show up on our dashboard as "Show Ads".
@Variable(name="Show Ads") public static boolean showAds = false;  // Whether or not to show ads in the app.

// Boolean with custom name: the variable showAds will show up on our dashboard as "Show Ads".
Var<bool> showAds = Var<bool>.Define("Show Ads", false);
...
void ShowAds() {
  if (showAds.Value) {
    MakeAdBanner();
  }
}

Dictionary

//Define the variable and set the name and value using the Var class, with dictionary.
//To access a dictionary value in your code, use the objectForKey method to get to the correct property, then use an accessor method (boolValue, floatValue, etc.) to get the actual value. 
//In Swift, you may need to cast after using objectForKey.

let powerUp = Var(name: "powerUp", dictionary: [
  "name": "Turbo Boost",
  "price": 150,
  "speedMultiplier": 1.5,
  "timeout": 15])

...
Leanplum.onVariablesChanged {
  self.speed = (powerUp?.object(forKey: "speedMultiplier") as! NSNumber).floatValue
}

//Set the value with the macro DEFINE_VAR_DICTIONARY_WITH_OBJECTS_AND_KEYS. To access a dictionary value in your code, use the objectForKey method to get to the correct property, then use an accessor method (stringValue, boolValue, floatValue, etc.) to get the actual value. 

DEFINE_VAR_DICTIONARY_WITH_OBJECTS_AND_KEYS(
  powerUp,
  @"Turbo Boost", @"name",
  @150, @"price",
  @1.5, @"speedMultiplier",
  @15, @"timeout",
  nil);
...
[Leanplum onVariablesChanged:^() {
  self.speed *= [[powerUp objectForKey:@"speedMultiplier"] floatValue];
}];

@Variable public static Map<String, Object> powerup = new HashMap<String, Object>() {
    {
        put("name", "Turbo Boost");
        put("price", 150);
        put("speedMultiplier", 1.5);
        put("timeout", 15);
        put("slots", Arrays.asList(1, 2, 3));
    }
};

Dictionary<string, object> powerupInit = new Dictionary<string, object>();
powerupInit.Add("price", 150);
powerupInit.Add("speedMultiplier", 1.5);
powerupInit.Add("timeout", 15);
Var<Dictionary<string, object>> powerup = Var<Dictionary<string, object>>.Define("powerup", powerupInit);

Array

//Define the variable and set the name and value using the Var class. 
//To access an array value in your code, use the objectAtIndex method to get to the correct object, then use an accessor method (boolValue, floatValue, etc.) to get the actual value. 
//In Swift, you may need to cast after using objectAtIndex.

let storeItemsOrder = Var(name: "storeItemsOrder", array: [0, 1, 2, 3, 4])
Leanplum.onVariablesChanged {
  for var i in 0..<storeItemsOrder!.count(){
    let item = storeItemsOrder!.object(at: i) as! NSNumber
    print(item.intValue)
    i += 1
  }
}

//Set the value with the macro DEFINE_VAR_ARRAY_WITH_OBJECTS.  To access a dictionary value in your code, use the objectAtIndex method to get to the correct object, then use an accessor method (stringValue, boolValue, floatValue, etc.) to get the actual value.

DEFINE_VAR_ARRAY_WITH_OBJECTS(storeItemsOrder, @0, @1, @2, @3, @4, nil);
...
[Leanplum onVariablesChanged:^(){
  for (int i = 0; i < storeItemsOrder.count; i++) {
    int item = [[storeItemsOrder objectAtIndex:i] intValue];
    NSLog(@"%i", item);
  }
}];

@Variable public static List<Integer> storeItemsOrder = Arrays.asList(1, 2, 3, 4);

Var<List<Object>> storeItemsOrder = Var<List<Object>>.Define("storeItemsOrder", new List<Object> { 0, 1, 2, 3, 4 });

Leanplum Assets

File variables work like variables except that the file data comes back from Leanplum separately. When you edit a file variable, you change its filename. If a file with the same name does not exist on the device, it will download from Leanplum.

//Define the variable and set the name and value using the Var class. Use the overload with file. 
//To access the value in your code, use the fileValue or imageValue method.

// Image
var goldStar = Var(name: "goldStar", file: "gold_star.png") // Location of Gold Star image file.
...
Leanplum.onVariablesChanged {
  self.splashView?.image = goldStar.imageValue()
}

//Set the value with the macro DEFINE_VAR_FILE. To access the value in your code, use the fileValue or imageValue method.

// Image and file.
DEFINE_VAR_FILE(goldStar, @"gold_star.png");  // Location of Gold Star image file.
DEFINE_VAR_FILE(config, @"config.plist");
...
[Leanplum onVariablesChanged:^() {
  // imageValue is compatible with Asset Catalogs.
  self.splashView.image = goldStar.imageValue;
  NSDictionary* config = [NSDictionary dictionaryWithContentsOfFile:config.fileValue];
}];

public static Var<String> mario = Var.defineAsset("Mario", "Mario.png");
...
mario.addFileReadyHandler(new VariableCallback<String>() {
    @Override
    public void handle(Var<String> variable) {
        im.setImageBitmap(BitmapFactory.decodeStream(mario.stream()));
    }
});

// It is necessary to specify platform-specific AssetBundles as they are not cross-platform.
// The filenames specified when defining an AssetBundle represent the default
// bundles that will be loaded if present in Leanplum's file manager.

Var<AssetBundle> background = Var<AssetBundle>.DefineAssetBundle(
    "forestBackground",
    standaloneBundleName: "Standalone-Forest.unity3d",
    androidBundleName: "Android-Forest.unity3d",
    iosBundleName: "iOS-Forest.unity3d");
...
void LoadBackground() {
  if (background.Value != null) {
    Instantiate(background.Value.mainAsset);
  }
}

Color

//Define the variable and set the name and value using the Var class. To access the value in your code, use the colorValue method.

var myColor = Var(name: "myColor", color: UIColor.gray)
...
Leanplum.onVariablesChanged {
  startButton.setTitleColor(myColor.colorValue(), for: .normal)
}

//Set the value with the macro DEFINE_VAR_COLOR. To access the value in your code, use the colorValue method.

DEFINE_VAR_COLOR(myColor, [UIColor colorWithRed:14.0/255.0 green:114.0/255.0 blue:199.0/255.0 alpha:1]);
...
[Leanplum onVariablesChanged:^() {
  [startButton setTitleColor:myColor.colorValue];
}];

Next: Implementation

Now that you are familiar with types and examples of variables within Leanplum, follow the Variable Implementation below to set up your first variable.