Flutter 集成（A/B Testing）

引入神策 Flutter 插件

在 pubspec.yaml 中添加 A/B Testing Flutter 插件：

dependencies:
  abtesting_sdk_flutter: ^1.0.0

初始化 SDK

在神策分析中创建 A/B Testing 后，会生成分流试验请求 URL，通过该 URL 初始化 A/B Testing SDK：

import 'package:abtesting_sdk_flutter/abtesting_sdk_flutter.dart';

// 注意需要在埋点 SDK 初始化后初始化 A/B Testing SDK
// A/B Testing SDK 初始化
SensorsABTest.startWithConfigOptions("分流试验请求地址");

Flutter 中获取试验变量

初始化 SDK 之后，通过 API 获取具体试验的变量值，根据获取试验变量值的方式，可分为下面三种策略：

fetchCacheABTest ：读取本地缓存，缓存不存在时使用默认值
asyncFetchABTest ：忽略本地缓存，从服务端获取数据
fastFetchABTest ：优先读取本地缓存，缓存不存在时从服务端获取数据

如何确定应该选择哪个API获取试验变量值？

1.一般情况下，我们推荐使用fastFetchABTest获取试验变量值。

2.如果您对性能有要求，可以使用fetchCacheABTest, 只从本地缓存中获取变量值，但可能导致用户无法及时命中最新的试验。

3.如果您进行时间片轮转试验，且对时效性有要求，可以使用asyncFetchABTest 获取试验变量值，但会存在一定的网络延迟。

1. 请确保对A/B分流返回的 result 结果 & 接口中使用的默认值，都做了正常的业务逻辑处理！

2. 请确保默认值 default_value 和当前试验值类型相同。比如参数对应试验值为 Int 类型，则传入的 default_value 也必须是 Int 类型，同时返回的试验结果 result 也是 Int 类型.

以 fastFetchABTest 为例，可在相应的业务逻辑中添加如下代码：

import 'package:abtesting_sdk_flutter/abtesting_sdk_flutter.dart';


// int 类型试验（第二个参数 0，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值）
int? result = await SensorsABTest.fastFetchABTest("具体的 paramName", 0); 
	// TODO 根据 result 处理相应逻辑
switch (result) {
  case 0:
    break;
  case 1:
    // 试验组 1 的处理逻辑  
    break;
  case 2:
    // 试验组 2 的处理逻辑
    break;
  // ……
  // …… 
  default:
    // 其他情况的处理逻辑
}

注意

如果您的项目不支持 Null safety ，请使用如下方式获取实验结果：
 int result = await SensorsABTest.fastFetchABTest("具体的 paramName", 0);  
// TODO 根据 result 处理相应逻辑

携带自定义属性获取试验变量

单次获取试验携带自定义属性

v1.0.0 及以上版本 Flutter AB SDK 支持自定义属性扩充受众筛选能力，可以在初始化 SDK 后，通过 API 添加自定义属性获取具体试验的变量值，根据获取试验变量值的方式，可分为下面 2 种策略：

asyncFetchABTest：忽略本地缓存，从服务端获取数据
fastFetchABTest：优先读取本地缓存，缓存不存在时从服务端获取数据

asyncFetchABTest 和 fastFetchABTest 接口会在主线程回调试验变量值

以 fastFetchABTest 为例，可在相应的业务逻辑中添加如下代码：

var experiment = SensorsABTestExperiment.experimentWithParamName("color", "color默认值");
// 设置自定义属性
experiment.properties = {"key1": "value1"};
SensorsABTest.fastFetchABTestWithExperiment<String>(experiment)
    .then((value) {
// TODO 根据 value 进行业务处理
});

设置全局自定义属性

通过初始化 SDK 或者接口动态设置全局自定义属性，后续所有获取试验分流场景，都会包含自定义属性筛选。

版本要求

A/B Testing Flutter 插件 >= v1.0.0

初始化接口设置自定义属性

var map = {"自定义属性 key": "自定义属性对应 value"};
SensorsABTest.startWithConfigOptions( "分流地址 url", map);

在 App 运行过程中，根据需要，也可以动态重置自定义属性（重新设置后，会覆盖初始化设置的自定义属性内容）。后续分流请求，都会包含新设置的自定义属性

 // 设置自定义属性
SensorsABTest.setCustomProperties( {"custom_properties_1": "custom_value_1"});

自定义属性值支持字符串、字符串数组、数值、布尔和日期时间格式，并且属性名支持英文、数字、下划线，且不能以数字开头。

获取设备主体试验变量

SDK支持使用设备主体进行分流。需要您在初始化SDK时，将匿名ID设置为公共属性。初始化并设置公共属性的具体方式如下：

// 必须先初始化神策分析 Flutter 插件（参考文档 https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_flutter_plugin）

// A/B Testing SDK 初始化
SensorsABTest.startWithConfigOptions("分流请求地址");

// 设备主体分流需要将匿名ID设置为公共属性
final anonymousId = SensorsAnalyticsFlutterPlugin.getAnonymousId();
SensorsAnalyticsFlutterPlugin.registerSuperProperties({'anonymous_id': anonymousId});

后续可以使用

fetchCacheABTest ：读取本地缓存，缓存不存在时使用默认值
asyncFetchABTest ：忽略本地缓存，从服务端获取数据
fastFetchABTest ：优先读取本地缓存，缓存不存在时从服务端获取数据

三种方式分别 获取试验变量

携带自定义主体获取试验变量

v1.0.0 及以上版本支持使用自定义主体进行分流。在接入前，需要您确认以下几点：

确认您要使用的自定义主体参数名（例如 phone_number, account 等，支持自定义）。
在神策元数据管理将该自定义主体设置为公共属性。
将自定义主体参数名提供给神策，由神策技术人员将其配置到分流服务后台。

在SDK初始化后，将您使用的自定义主体设置为公共属性，并在调用获取试验变量API时，手动将其添加到接口请求参数custom_ids字典中。具体方式如下：

// 必须先初始化神策分析 Flutter 插件（参考文档 https://manual.sensorsdata.cn/sa/docs/tech_sdk_client_flutter_plugin）

// A/B Testing SDK 初始化
SensorsABTest.startWithConfigOptions("分流请求地址 url");

//自定义主体分流需要将自定义主体名设置为公共属性，并将其加入分流请求中
SensorsAnalyticsFlutterPlugin.registerSuperProperties({"custom_id1": "custom_value_1"});
SensorsABTest.setCustomIDs({"custom_id_1": "custom_value_1"});

后续可以使用

fetchCacheABTest ：读取本地缓存，缓存不存在时使用默认值
asyncFetchABTest ：忽略本地缓存，从服务端获取数据
fastFetchABTest ：优先读取本地缓存，缓存不存在时从服务端获取数据

三种方式分别 获取试验变量

调试试验

对于 iOS 需要在 AppDelegate 的 - application:openURL:options: 方法中调用 -handleOpenURL: 对神策 A/B Testing Scheme 进行处理：

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
     
    if ([[SensorsABTest sharedInstance] handleOpenURL:url]) {
        return YES;
    }
    return NO;
}

先将设备录入到调试设备管理列表中，在创建试验时，直接将指定调试设备录入到对应试验分组。

录入前请确保 App 已正确配置 Scheme（Android）

录入前请确保 App 已正确配置 Scheme（iOS）

调试设备在调试状态和正式上线阶段都会生效