Server Persistent Assignment

Persistent assignment allows you to ensure that a user’s variant stays consistent while an experiment is running, regardless of changes to allocation or targeting.

Persistent Storage Adapter

The persistent storage adapter allows you to plug in your own storage solution that Statsig SDK uses to persist user assignments. The storage interface consists of just a load and save API for read/write operations.

Currently only supported in Go, Ruby, Legacy Node, Node Core, Java Core, Kotlin, .Net, Python Core, PHP Core, Rust Core

Persistent Storage Logic

• Providing a storage adapter on Statsig initialization will give the SDK access to read & write on your custom storage
• Providing user persisted values to get_experiment will inform the SDK to
  • save the evaluation of the current user on first evaluation
    • Will only save when experiment / layer is active
  • load the previously saved evaluation of a persisted user on subsequent evaluations
• CAVEAT Persisted Value will be deleted when:
  • When you provided call getExperiment with user_persisted_values=None
  • or When experiment is not active

Persistent Assignment Options (Limited SDK Support)

• Enforce Targeting: boolean, default: false
  • Whether or not to enforce targeting rules before assigning persisted values

Kotlin

val options = GetExperimentOptions(
  ...
  persistentAssignmentOptions = PersistentAssignmentOptions(
    enforceTargeting = true,
  )
)

Node JS

const options: GetExperimentOptions = {
  ...
  persistentAssignmentOptions: {
    enforceTargeting: true,
  }
}

Example usage

Ruby

Statsig.initialize(
  'secret-key',
  StatsigOptions.new(
    user_persistent_storage: DummyPersistentStorageAdapter.new
  )
)
persisted_user = StatsigUser.new({ 'userID' => 'test-123' })
exp = Statsig.get_experiment( # User gets saved to persisted storage
  persisted_user,
  'active_experiment',
  Statsig::GetExperimentOptions.new(
    user_persisted_values: Statsig.get_user_persisted_values(persisted_user, 'userID')
  )
)
puts exp.group_name # 'Control'
exp = Statsig.get_experiment( # User evaluates using values from persisted storage
  StatsigUser.new({'userID' => 'unknown'}),
  'active_experiment',
  Statsig::GetExperimentOptions.new(
    user_persisted_values: Statsig.get_user_persisted_values(persisted_user, 'userID')
  )
)
puts exp.group_name # 'Control'

Python (Python Core)

from statsig_python_core import Statsig, StatsigUser, StatsigOptions, ExperimentEvaluationOptions, PersistentStorage

options = StatsigOptions(persistent_storage = MyPersistentStorage())
statsig = Statsig.initialize(options).wait
user = StatsigUser("a-user")
exp = statsig.get_experiment(StatsigUser("a-user"), ExperimentEvaluationOptions(user_persisted_values= PersistentStorage.get_user_persisted_value(user, "user_id")))
print(f"{exp.group_name}") # control

Java Core

PersistentStorage persistentStorage = new MyPersistentStorage(); // See https://docs.statsig.com/server-core/java-core/#persistent-storage on how to implement it
StatsigOptions options = new StatsigOptions.Builder()
    .setPersistentStorage(persistentStorage)
    .build();

Statsig statsig = new Statsig("secret-key", options);
statsig.initialize().get();

StatsigUser persistedUser = new StatsigUser.Builder().setUserID("test-123").build();
Map<String, StickyValues> persistedValues = persistentStorage.getValuesForUser(persistedUser, "userID");
if (persistedValues == null) {
    persistedValues = new HashMap<>();
}

Experiment exp = statsig.getExperiment(
    persistedUser,
    "active_experiment",
    new GetExperimentOptions(persistedValues)
);
System.out.println(exp.getGroupName()); // "Control"

StatsigUser unknownUser = new StatsigUser.Builder().setUserID("unknown").build();
Map<String, StickyValues> valuesForPersistedUser = persistentStorage.getValuesForUser(persistedUser, "userID");
Experiment persistedExp = statsig.getExperiment(
    unknownUser,
    "active_experiment",
    new GetExperimentOptions(valuesForPersistedUser)
);
System.out.println(persistedExp.getGroupName()); // "Control"

Node Core

let persistedStorage =  new MyPersistentStorage() // See https://docs.statsig.com/server-core/node-core/#persistent-storage on how to implement it
let options = new StatsigOptions(persistentStorage = persistedStorage)
let statsig = new Statsig(secretKye, options)
let user = new StatsigUser("a-user")
let exp = statsig.getExperiment(user, ExperimentEvaluationOptions(userPersistentValues= persistedStorage.getUserPersistedValues(user, "user_id")))

PHP Core

$persistent_storage = new MyPersistentStorage(); // See https://docs.statsig.com/server-core/php-core/#persistent-storage on how to implement it
$options = new StatsigOptions(persistent_storage: $persistent_storage);

$statsig = new Statsig("secret-key", $options);
$statsig->initialize();

$persisted_user = new StatsigUser("test-123");
$persisted_values = $persistent_storage->getValuesForUser($persisted_user, "userID") ?? [];
$exp = $statsig->getExperiment(
    $persisted_user,
    "active_experiment",
    ["user_persisted_values" => $persisted_values],
);
echo $exp->groupName; // "Control"

$unknown_user = new StatsigUser("unknown");
$values_for_persisted_user = $persistent_storage->getValuesForUser($persisted_user, "userID");
$persisted_exp = $statsig->getExperiment(
    $unknown_user,
    "active_experiment",
    ["user_persisted_values" => $values_for_persisted_user],
);
echo $persisted_exp->groupName; // "Control"

Rust Core

let persistent_storage = Arc::new(MyPersistentStorage::new()); // See https://docs.statsig.com/server-core/rust-core/#persistent-storage on how to implement it
let options = StatsigOptions::builder()
    .persistent_storage(Some(persistent_storage.clone()))
    .build();

let statsig = Statsig::new("secret-key", Some(Arc::new(options)));
statsig.initialize().await;

let persisted_user = StatsigUser::with_user_id("test-123");
let persisted_values = persistent_storage
    .get_values_for_user(&persisted_user, "userID")
    .unwrap_or_default();
let exp = statsig.get_experiment_with_options(
    &persisted_user,
    "active_experiment",
    ExperimentEvaluationOptions {
        user_persisted_values: Some(persisted_values),
        ..Default::default()
    },
);
println!("{}", exp.group_name.as_deref().unwrap_or("")); // "Control"

let unknown_user = StatsigUser::with_user_id("unknown");
let values_for_persisted_user = persistent_storage.get_values_for_user(&persisted_user, "userID");
let persisted_exp = statsig.get_experiment_with_options(
    &unknown_user,
    "active_experiment",
    ExperimentEvaluationOptions {
        user_persisted_values: values_for_persisted_user,
        ..Default::default()
    },
);
println!("{}", persisted_exp.group_name.as_deref().unwrap_or("")); // "Control"

Kotlin

runBlocking {
  Statsig.initialize(
    "secret-key",
    StatsigOptions(userPersistentStorage = MyPersistentStorageAdapter())
  )
}
val persistedUser = StatsigUser("test-123")
var exp = Statsig.getExperimentSync(
  persistedUser,
  "active_experiment",
  GetExperimentOptions(
    userPersistedValues = Statsig.getUserPersistedValues(persistedUser, "userID"),
  ),
)
println(exp.groupName) // "Control"
exp = Statsig.getExperimentSync(
  StatsigUser("unknown"),
  "active_experiment",
  GetExperimentOptions(
    userPersistedValues = Statsig.getUserPersistedValues(persistedUser, "userID"),
  ),
)
println(exp.groupName) // "Control"

Node JS

await Statsig.initialize(
  "secret-key",
  {
    userPersistentStorage: new MyPersistentStorageAdapter() 
  }
)
const persistedUser: StatsigUser = { userID: "123" }
let exp = Statsig.getExperimentSync(
  persistedUser,
  "active_experiment",
  { 
    userPersistedValues: Statsig.getUserPersistedValues(user, "userID")
  },
)
console.log(exp.getGroupName()) // "Control"
exp = Statsig.getExperimentSync(
  { userID: "unknown" },
  "active_experiment",
  { 
    userPersistedValues: Statsig.getUserPersistedValues(user, "userID")
  },
)
console.log(exp.getGroupName()) // "Control"

Go

InitializeWithOptions(
  "secret-key",
  &Options{
    UserPersistentStorage: persistentStorage,
  }
)
persistedUser := User{UserID: "123"}
exp := GetExperimentWithOptions(
  persistedUser,
  "active_experiment",
  &GetExperimentOptions{
    PersistedValues: GetUserPersistedValues(persistedUser, "userID")
  }
)
fmt.Println(exp.GroupName) // "Control"
exp = GetExperimentWithOptions(
  User{UserID: "unknown"},
  "active_experiment",
  &GetExperimentOptions{
    PersistedValues: GetUserPersistedValues(persistedUser, "userID")
  }
)
fmt.Println(exp.GroupName) // "Control"

.Net

var options = new StatsigServerOptions();
options.UserPersistentStorage = new MyPersistentStorageAdapter()
await StatsigServer.Initialize("server-secret-key", options);

var persistedUser = new StatsigUser { UserID = "123" };
var values = await StatsigServer.GetUserPersistedValues(persistedUser, "userID");
var getExpOptions = new StatsigGetExperimentOptions(values);
var exp = StatsigServer.GetExperimentSync(persistedUser, "active_experiment", getExpOptions);
Console.WriteLine(exp.GroupName); // "Control"

var newValues = await StatsigServer.GetUserPersistedValues(persistedUser, "userID");
var newGetExpOptions = StatsigGetExperimentOptions(newValues);

var newExp = StatsigServer.GetExperimentSync(new StatsigUser {UserID = "unknown"}, "active_experiment", newGetExpOptions);
Console.WriteLine(newExp.GroupName); // "Control"