absmartly_sdk 1.0.0 absmartly_sdk: ^1.0.0 copied to clipboard
A/B Smartly - Flutter SDK.
A/B Smartly Flutter SDK #
A/B Smartly Flutter SDK
Compatibility #
The A/B Smartly Flutter SDK is compatible with Dart versions 2.18.6 and later.
Getting Started #
Install the SDK #
To install the ABSmartly SDK, place the following in your pubspec.yaml
and replace version with the latest SDK version available in pub.dev.
absmartly_sdk: ^version
Import and Initialize the SDK #
Once the SDK is installed, it can be initialized in your project.
void main() async{
final ClientConfig clientConfig = ClientConfig()
..setEndpoint("https://your-company.absmartly.io/v1")
..setAPIKey("YOUR API KEY")
..setApplication("website")
..setEnvironment("development");
final ABSmartlyConfig sdkConfig = ABSmartlyConfig.create()
.setClient(Client.create(clientConfig));
final ABSmartly sdk = ABSmartly(sdkConfig);
}
SDK Options
Config | Type | Required? | Default | Description |
---|---|---|---|---|
endpoint | string |
✅ | undefined |
The URL to your API endpoint. Most commonly "your-company.absmartly.io" |
apiKey | string |
✅ | undefined |
Your API key which can be found on the Web Console. |
environment | "production" or "development" |
✅ | undefined |
The environment of the platform where the SDK is installed. Environments are created on the Web Console and should match the available environments in your infrastructure. |
application | string |
✅ | undefined |
The name of the application where the SDK is installed. Applications are created on the Web Console and should match the applications where your experiments will be running. |
Using a Custom Event Logger #
The A/B Smartly Flutter SDK can be instantiated with an event logger used for all
contexts. In addition, an event logger can be specified when creating a
particular context, in the [CONTEXT_CONFIG_VARIABLE]
.
class CustomEventLogger implements ContextEventLogger {
@override
void handleEvent(Context context, EventType event, dynamic data) {
switch (event) {
case EventType.Exposure:
final Exposure exposure = data;
print("exposed to experiment ${exposure.name}");
break;
case EventType.Goal:
final GoalAchievement goal = data;
print("goal tracked: ${goal.name}");
break;
case EventType.Error:
print("error: $data");
break;
case EventType.Publish:
case EventType.Ready:
case EventType.Refresh:
case EventType.Close:
break;
}
}
}
contextConfig.setContextEventLogger(CustomEventLogger());
The data parameter depends on the type of event. Currently, the SDK logs the following events:
eventName | when | data |
---|---|---|
"error" |
Context receives an error |
error object thrown |
"ready" |
Context turns ready |
data used to initialize the context |
"refresh" |
Context.refresh() method succeeds |
data used to refresh the context |
"publish" |
Context.publish() method succeeds |
data sent to the A/B Smartly event collector |
"exposure" |
Context.treatment() method succeeds on first exposure |
exposure data enqueued for publishing |
"goal" |
Context.track() method succeeds |
goal data enqueued for publishing |
"finalize" |
Context.finalize() method succeeds the first time |
undefined |
Create a New Context Request #
Synchronously
createNewContext() async{
final ContextConfig contextConfig = ContextConfig.create()
.setUnit("session_id", "5ebf06d8cb5d8137290c4abb64155584fbdb64d8"); // a unique id identifying the user
final Context? context = sdk.createContext(contextConfig)
.waitUntilReady();
if(context != null){
print("context ready");
}
}
Asynchronously
createNewContext() async{
final ContextConfig contextConfig = ContextConfig.create()
.setUnit("session_id", "5ebf06d8cb5d8137290c4abb64155584fbdb64d8"); // a unique id identifying the user
final Context? context = await sdk.createContext(contextConfig)
.waitUntilReady();
if(context != null){
print("context ready");
}
}
With Prefetched Data
final ContextConfig contextConfig = ContextConfig.create()
.setUnit("session_id", "5ebf06d8cb5d8137290c4abb64155584fbdb64d8"); // a unique id identifying the user
final Context context = sdk.createContext(contextConfig)
.waitUntilReady();
final ContextConfig anotherContextConfig = ContextConfig.create()
.setUnit("session_id", "5ebf06d8cb5d8137290c4abb64155584fbdb64d8"); // a unique id identifying the other user
final Context anotherContext = sdk.createContextWith(anotherContextConfig, context.getData());
assert(anotherContext.isReady()); // no need to wait
Refreshing the Context with Fresh Experiment Data
For long-running contexts, the context is usually created once when the application is first started. However, any experiments being tracked in your production code, but started after the context was created, will not be triggered. To mitigate this, we can use the setRefreshInterval()
method on the context config.
final ContextConfig contextConfig = ContextConfig.create()
.setUnit("session_id", "5ebf06d8cb5d8137290c4abb64155584fbdb64d8")
.setRefreshInterval(TimeUnit.HOURS.toMillis(4)); // every 4 hours
Alternatively, the refresh()
method can be called manually. The refresh()
method pulls updated experiment data from the A/B Smartly collector and will trigger recently started experiments when getTreatment()
is called again.
context.refresh()
Setting Extra Units
You can add additional units to a context by calling the setUnit()
or
setUnits()
methods. These methods may be used, for example, when a user
logs in to your application and you want to use the new unit type in the
context.
Please note, you cannot override an already set unit type as that would be
a change of identity and would throw an exception. In this case, you must
create a new context instead. The setUnit()
and
setUnits()
methods can be called before the context is ready.
context.setUnit("db_user_id", "1000013");
context.setUnits({
"db_user_id": "1000013"
});
Basic Usage #
Selecting A Treatment #
if((await context.getTreatment("exp_test_experiment")) == 0) {
// user is in control group (variant 0)
} else {
// user is in treatment group
}
Treatment Variables #
var defaultButtonColorValue = "red"
context.getVariableValue("experiment_name", defaultButtonColorValue)
Peek at Treatment Variants #
Although generally not recommended, it is sometimes necessary to peek at
a treatment or variable without triggering an exposure. The A/B Smartly
SDK provides a peekTreatment()
method for that.
final dynamic variable = context.getVariable("my_variable");
Peeking at variables
var value = await ctx.peekTreatment("experimentName");
Overriding Treatment Variants #
During development, for example, it is useful to force a treatment for an experiment. This can be achieved with the override()
and/or overrides()
methods. The setOverride()
and setOverrides()
methods can be called before the context is ready.
context.setOverride(experimentName, variant)
context.setOverrides({
"exp_test_experiment": 1,
"exp_another_experiment": 0,
});
Advanced #
Context Attributes #
Attributes are used to pass meta-data about the user and/or the request.
They can be used later in the Web Console to create segments or audiences.
They can be set using the setAttribute()
or setAttributes()
methods, before or after the context is ready.
context.setAttribute("attribute", 1);
context.setAttributes(
{
"attribute": 1,
},
);
Custom Assignments #
Sometimes it may be necessary to override the automatic selection of a
variant. For example, if you wish to have your variant chosen based on
data from an API call. This can be accomplished using the
setCustomAssignment()
method.
context.setCustomAssignment("experimentName", 1);
context.setCustomAssignments({"experimentName": 1});
If you are running multiple experiments and need to choose different
custom assignments for each one, you can do so using the
getCustomAssignment()
method.
context.getCustomAssignment("experimentName");
Publish #
Sometimes it is necessary to ensure all events have been published to the A/B Smartly collector, before proceeding. You can explicitly call the publish()
or publishAsync()
methods.
context.publish();
Finalize #
The close()
and closeAsync()
methods will ensure all events have been published to the A/B Smartly collector, like publish()
, and will also "seal" the context, throwing an error if any method that could generate an event is called.
context.close();
Tracking Goals #
Goals are created in the A/B Smartly web console.
context.track("payment",{
"item_count": 1,
"total_amount": 1999.99
});