菜单

C# SDK 集成 （A/B Testing）

C# A/B Testing SDK 依赖于神策分析 SDK，在使用前请确保已经成功集成神策分析 SDK，并进行了 SDK 初始化，详情可参考 SDK 集成 (C#）

C# A/B Testing  支持 .Net Core 2.0+ 和 .Net Framework 4.6.1+；同时支持通过 NuGet 方式发布和集成  A/B SDK。

集成 SDK

SDK 的工程源代码可以从 GitHub 上下载，并选用下面的一种方法进行集成：

  1. (推荐）通过 NuGet 方式直接引入我们的 SDK（Nuget 地址）；
  2. 对 SDK 源代码编译后从 Release 目录下取得  dll 文件用于集成；
  3. 将 SDK 项目其作为模块添加进需要集成的项目中使用。

初始化 SDK

C# A/B Testing SDK 依赖神策分析 SDK。请确保已经成功集成神策分析 SDK，并进行了 SDK 初始化。成功引入 A/B Testing SDK 之后，请先在神策分析前端页面创建相关的分流试验，然后获取生成的分流 URL。

//可以参考神策分析 SDK，选择不同的 Consumer
IConsumer consumer = new NewClientConsumer("神策分析服务地址",           
    "本地日志路径", 10, 10 * 1000);           
SensorsAnalytics sa = new SensorsAnalytics(consumer, true);           
ABTestConfig config = ABTestConfig.builder()           
    .SetSensorsAnalytics(sa)           
    .SetApiUrl("分流试验请求地址")           
    .EnableEventCache(false)           
    .Build();
SensorsABTest sensorsABTest = new SensorsABTest(config);

在实际开发中，建议将 SensorsAnalytics 对象保存为单例，有可能的话将 SensorsABTest 也保存未单例。

初始化 Api 参数说明

C# A/B Testing SDK 的全局参数封装在 ABTestConfig 类中，具体参数如下：

参数名类型说明
eventCacheTimeint单用户事件缓存时间，默认值为 1440min，最大限制 1440min，最小限制 0min

eventCacheSize

int

事件总缓存用户量,默认值为 4096，无上限设置，最小限制 3

experimentCacheSize

int

试验总缓存用户量，默认值 4096，无上限设置，最小限制 3

experimentCacheTime

int

单用户试验缓存时间，默认值为 1440min，最大限制 1440min，最小限制 0min

enableEventCachebool上报事件缓存开关，默认开启缓存
apiUrlstring

分流试验地址，必填，默认为空

sensorsAnalytics

SensorsAnalytics

神策分析 SDK 实例对象，必填，默认为空（此处使用神策分析 SDK 版本为 3.2.0 及以上版本）

获取试验变量 

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

  • AsyncFetchABTest：忽略内存缓存，从服务端获取数据；
  • FastFetchABTest：优先读取内存缓存，缓存不存在时从服务端获取数据。

应该选择哪个API获取试验变量值？

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

2.如果您进行的是时间片轮转等在试验过程中用户会进入不同组的试验，建议您使用AsyncFetchABTest，直接从服务端获取数据，保证获取变量的准确性。

1. 接入前请参考如何设置distinctId，在调用时正确设置distinctId参数.

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

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

如果您需要在新用户注册流程中使用A/B Testing服务端SDK对新用户进行用户主体分流试验，不建议您使用loginId请求分流。可参考以下方案，根据您试验的实际情况选择其中一个：

  1. 如果您目前的A/B Testing 版本在v0.9.1以上，可以在创建试验时采用登录ID作为试验的分流主体。
  2. 如果用户只会在一台设备登录，没有多设备登录场景，可使用客户端设备的匿名ID请求分流，即distinctId为从客户端获取的匿名ID，isLoginId为false.
  3. 可以将试验移到客户端进行。
  4. 可以使用服务端SDK进行自定义主体分流试验。

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

// 具体的用户 ID 标识
string distinctId = "fz123456"; 
// 当前用户是否是登录 ID
bool isLoginId = true; 

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

获取实验变量请求参数说明

参数名类型说明
distinctIdstring具体的用户 ID 标识
isLoginIdstring当前用户是否是登录 ID
experimentVariableNamestring试验变量名称(具体的试验参数)
defaultValuenumber｜bool｜string｜json string未命中试验，返回默认值
enableAutoTrackEventbool是否开启自动上报 $ABTestTrigger 事件，默认自动上报
timeoutMillisecondsint请求超时设置 默认 3000ms
propertiesDictionary<string, object>自定义属性，默认值为 null

方法返回值说明

C# A/B Testing SDK 统一返回 Experiment<T>对象，具体返回参数如下：

参数名类型说明

distinctId

string具体的用户 ID 标识

isLoginId

bool当前用户是否是登录 ID

abTestExperimentId

string试验 ID

abTestExperimentGroupId

string试验分组 ID
isWhiteListbool是否白名单用户，白名单用户不进行试验事件的上报
isControlGroupbool是否是对照组

result

T 范型试验命中返回值，目前支持类型 ：number｜bool｜string｜json string

使用示例

//可以参考神策分析 SDK，选择不同的 Consumer
IConsumer consumer = new NewClientConsumer("神策分析服务地址",           
    "本地日志路径", 10, 10 * 1000);           
SensorsAnalytics sa = new SensorsAnalytics(consumer, true);           
ABTestConfig config = ABTestConfig.builder()           
    .SetSensorsAnalytics(sa)           
    .SetApiUrl("分流试验请求地址")           
    .EnableEventCache(false)           
    .Build();
SensorsABTest sensorsABTest = new SensorsABTest(config);           
Experiement<string> experiement = sensorsABTest.AsyncFetchABTest<string>("AB123456", false, "param_cat", 
	"hello", timeoutMilliseconds: 3000, enableAutoTrackEvent: false);       
//当 enableAutoTrackEvent 设置为 false，需要添加该代码，否则不需要
sensorsABTest.TrackABTestTriggerEvent<string>(experiement);           
//本地测试时可以设置，保证事件能上传成功。
Thread.Sleep(5000);           
//一般在系统结束的时候调用此方法
sa.Shutdown();    

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

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

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

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

//可以参考神策分析 SDK，选择不同的 Consumer
IConsumer consumer = new NewClientConsumer("神策分析服务地址",           
    "本地日志路径", 10, 10 * 1000);           
SensorsAnalytics sa = new SensorsAnalytics(consumer, true);           
ABTestConfig config = ABTestConfig.builder()           
    .SetSensorsAnalytics(sa)           
    .SetApiUrl("分流试验请求地址")           
    .EnableEventCache(false)           
    .Build();
SensorsABTest sensorsABTest = new SensorsABTest(config);      

Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("自定义属性对应英文名", "自定义属性对应 value"); // 自定义属性

Experiement<string> experiement = sensorsABTest.AsyncFetchABTest<string>("AB123456", false, "param_cat", 
	"hello", timeoutMilliseconds: 3000, enableAutoTrackEvent: false, properties: properties);       
//当 enableAutoTrackEvent 设置为 false，需要添加该代码，否则不需要
sensorsABTest.TrackABTestTriggerEvent<string>(experiement);           
//本地测试时可以设置，保证事件能上传成功。
Thread.Sleep(5000);           
//一般在系统结束的时候调用此方法
sa.Shutdown();    

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

获取设备主体试验变量

接入前请参考如何设置distinctId，在调用时正确设置distinctId参数。获取设备主体试验变量时，distinctId为从客户端获取的匿名ID。

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

初始化SDK后，需要使用从客户端获取的匿名ID调用获取试验变量API，添加anonymous_id属性后手动上报$ABTestTrigger事件，且需要在后续上报的事件中添加anonymous_id作为事件属性。

string distinctId = "anonymous_id"; // 匿名ID
bool isLoginId = false; // 当前distinctId不是登录ID

// Integer 类型试验（第四个参数 0，表示未命中试验时，会返回此默认值，请根据业务需要更改此处的值）
// 第五个参数是false, 设置为手动上报$ABTestTrigger事件
Experiment<Integer> experiment = sensorsABTest.FastFetchABTest(distinctId, isLoginId, "具体的试验参数", 0, false);

//手动上报$ABTestTrigger事件，将anonymous_id作为事件属性 
Dictionary<string, object> anonymousIdMap = new Dictionary<string, object>();
anonymousIdMap.Add("anonymous_id", distinctId);
sensorsABTest.TrackABTestTriggerEvent(experiment, anonymousIdMap);

int result = experiment.getResult();                
// TODO 根据 result 处理相应逻辑
        switch (result) {
            case 0:
                break;
            case 1:
                // 试验组 1 的处理逻辑
                break;
            case 2:
                // 试验组 2 的处理逻辑
                break;
            // ……
            // ……
            default:
                // 其他情况的处理逻辑
                break;
        }


//如果需要上报事件参与AB设备主体试验指标计算，需要在每条埋点事件中将anonymous_id作为事件属性上报，如下所示
Dictionary<string, object> properties = new Dictionary<string, object>();
properties.Add("anonymous_id", distinctId);     //将anonymous_id作为事件属性上报
properties.Add("$is_login_id", false);  
properties.Add("price", 100);
sa.Track(distinctId, "buy", properties)

手动触发 A/B 测试（$ABTestTrigger）事件说明

C# A/B Testing SDK 中提供的方法中，如果设置参数 enableAutoTrackEvent=true 或者不设置，并且事件内存缓存中不存在，SDK 会自动上报 A/B 测试（$ABTestTrigger）事件。

如果设置 enableAutoTrackEvent=false ，则需要用户自己手动触发上报 A/B 测试（$ABTestTrigger）事件


调试试验

  1. 可以通过录入调试设备的方式，把 C#  用户加入指定分组中；加入调试设备后，会强制命中当前试验指定的分组（调试设备在调试状态和正式上线阶段都会生效）。
  2. 集成神策分析 C# SDK 后，在控制台中查看任意一条数据，可以获取当前用户的 distinct_id。
  3. 将此 distinct_id 对应的值复制录入调试设备列表中，在创建试验时，直接将指定调试设备录入到对应试验分组。

上一个
C++ SDK 集成（A/B Testing）
下一个
Flutter 集成（A/B Testing）
最近修改: 2024-12-27