Go SDK--A/B测试-火山引擎

文档中心

导航

Go SDK

最近更新时间：2024.11.07 17:04:40首次发布时间：2023.04.20 14:24:34

1. 安装SDK

go get github.com/volcengine/datatester-go-sdk@v1.0.5

当前SDK版本：v1.0.5
Go版本要求：go1.14及以上版本

2. 使用示例

2.1 SaaS-云原生

package main
import (
        "github.com/volcengine/datatester-go-sdk/client"
        "github.com/volcengine/datatester-go-sdk/config"
)
func main() {
        // token获取方式详见接口描述-AbClient
        abClient := client.NewClient("token",
        config.WithMetaHost("https://tab.volces.com"), // 默认使用国内SAAS域名，私有化/SaaS-云原生用户需要修改
        config.WithTrackHost("https://gator.volces.com") // 默认使用国内SAAS域名，私有化/SaaS-云原生用户需要修改
        )
        /*
           client.NewClient("appKey"),
           config.WithWorkerNumOnce(20), // 事件上报协程数，一般不需要设置
           config.WithFetchInterval(60 * time.Second), // meta更新间隔，默认为60s，一般不需要设置
           config.WithAnonymousConfig(true, true), // 匿名上报配置，第一个参数为开启关闭，第二个参数区分SaaS-非云原生和SaaS-云原生
           config.WithLogger(log.NewLogrusAdapt(logrus.New()))) // 自定义日志接口，提供默认实现
        */

        // attributes: 用户属性，仅用于分流，不随埋点上报，可参考https://www.volcengine.com/docs/6287/65826
        attributes := map[string]interface{}{
        }
        // decisionId(ssid): 本地分流用户标识，不用于事件上报，请替换为客户的真实用户标识
        // trackId(uuid): 事件上报用户标识，用于事件上报，请替换为客户的真实用户标识
        value, err := abClient.Activate("${experiment_key}", "decisionId", "trackId", true, attributes)
        // 未命中实验和ff的场景下返回固定err且不为空，value返回传入的默认值，可按需使用
        // if err != nil {
        //   
        //}
}

2.2 SaaS-非云原生(老客)

package main
import (
        "github.com/volcengine/datatester-go-sdk/client"
        "github.com/volcengine/datatester-go-sdk/config"
)
func main() {
        // token获取方式详见接口描述-AbClient
        abClient := client.NewClient("token")
        /*
           client.NewClient("appKey"),
           config.WithWorkerNumOnce(20), // 事件上报协程数，一般不需要设置
           config.WithFetchInterval(60 * time.Second), // meta更新间隔，默认为60s，一般不需要设置
           config.WithAnonymousConfig(true, true), // 匿名上报配置，第一个参数为开启关闭，第二个参数区分SaaS-非云原生和SaaS-云原生
           config.WithLogger(log.NewLogrusAdapt(logrus.New()))) // 自定义日志接口，提供默认实现
        */

        // attributes: 用户属性，仅用于分流，不随埋点上报，可参考https://www.volcengine.com/docs/6287/65826
        attributes := map[string]interface{}{
        }
        // decisionId(ssid): 本地分流用户标识，不用于事件上报，请替换为客户的真实用户标识
        // trackId(uuid): 事件上报用户标识，用于事件上报，请替换为客户的真实用户标识
        value, err := abClient.Activate("${experiment_key}", "decisionId", "trackId", true, attributes)
        // 未命中实验和ff的场景下返回固定err且不为空，value返回传入的默认值，可按需使用
        // if err != nil {
        //   
        //}
}

2.3 私有化

package main
import (
        "github.com/volcengine/datatester-go-sdk/client"
        "github.com/volcengine/datatester-go-sdk/config"
)
func main() {
        // token获取方式详见接口描述-AbClient
        abClient := client.NewClient("token",
        config.WithMetaHost(""), // 私有化部署客户一般为产品域名，请根据实际的域名进行替换
        config.WithTrackHost(""),// 私有化部署客户为埋点数据上报申请的域名，请根据实际的域名进行替换
        )
        /*
           client.NewClient("appKey"),
           config.WithWorkerNumOnce(20), // 事件上报协程数，一般不需要设置
           config.WithFetchInterval(60 * time.Second), // meta更新间隔，默认为60s，一般不需要设置
           config.WithAnonymousConfig(true, true), // 匿名上报配置，第一个参数为开启关闭，第二个参数区分SaaS-非云原生和SaaS-云原生
           config.WithLogger(log.NewLogrusAdapt(logrus.New()))) // 自定义日志接口，提供默认实现
        */

        // attributes: 用户属性，仅用于分流，不随埋点上报，可参考https://www.volcengine.com/docs/6287/65826
        attributes := map[string]interface{}{
        }
        // decisionId(ssid): 本地分流用户标识，不用于事件上报，请替换为客户的真实用户标识
        // trackId(uuid): 事件上报用户标识，用于事件上报，请替换为客户的真实用户标识
        value, err := abClient.Activate("${experiment_key}", "decisionId", "trackId", true, attributes)
        // 未命中实验和ff的场景下返回固定err且不为空，value返回传入的默认值，可按需使用
        // if err != nil {
        //   
        //}
}

3. 接口描述

3.1 NewClient

接口：
NewClient(token string, configs ...config.Func) *AbClient
描述： 初始化ABTest分流
参数：

token：表明您的Tester应用。出于安全考虑，此处使用的token=appKey，而非appId。
在集团中接入一个应用后，您可以在集团相关页面查看应用的AppKey等信息，详情请参考：如何创建应用。
- SaaS-云原生
- SaaS-非云原生
说明
请尽早初始化AbClient，以免影响您的分流服务和埋点上报服务。
config.WithMetaHost：获取元信息的地址，默认为SaaS-非云原生国内地址；海外Saas域名：config.MetaHostSG；SaaS-云原生/私有化需要设置为产品域名
config.WithTrackHost：事件上报的地址，默认为SaaS-非云原生国内地址；海外Saas域名：config.TrackHostSG；SaaS-云原生/私有化需要设置为上报域名
config.WithFetchInterval(60 * time.Second)：meta更新间隔，默认为60s，一般不需要设置
config.WithWorkerNumOnce(20)：事件上报协程数，一般不需要设置
config.WithAnonymousConfig(true, true)：匿名上报配置，第一个参数为开启关闭，第二个参数区分saas和私有化；不使用匿名上报的场景下不需要设置
config.WithLogger(log.NewLogrusAdapt(logrus.New()))：自定义日志接口，提供默认实现

3.2 NewClientWithUserAbInfo

接口：
NewClientWithUserAbInfo(token string, userAbInfoHandler handler.UserAbInfoHandler, configs ...config.Func) *AbClient
描述： 初始化ABTest分流类，传入自定义的userAbInfoHandler，userAbInfoHandler详见文档末尾

3.3 Activate

接口： func (t *AbClient) Activate(variantKey, decisionId, trackId string, defaultValue interface{}, attributes map[string]interface{}) (interface{}, error)
描述： 获取特定key的分流结果，并上报曝光事件
参数：
variantKey：变体的key
decisionId：本地分流用户标识
trackId：事件上报用户标识
defaultValue：变体默认值
attributes：用户属性
返回值： 该函数返回命中变体对象，未命中时返回默认值对象

说明

1、该接口与所有含有“WithImpression”字样的接口均会自动上报曝光事件，用户可在AbClient初始化时指定domain，调整事件上报地址。
2、请务必填写trackId字段，否则上报失效

3.4 GetExperimentVariantName

接口： func (t *AbClient) GetExperimentVariantName(experimentId, decisionId string, attributes map[string]interface{}) (string, error)
描述： 获取用户命中的特定实验的版本名称
参数：
experimentId：指定分流的实验Id
decisionId：本地分流用户标识
attributes：用户属性
返回值： 该函数返回用户命中的特定实验的版本名称

3.5 GetExperimentConfigs

接口： func (t *AbClient) GetExperimentConfigs(experimentId, decisionId string, attributes map[string]interface{}) (map[string]map[string]interface{}, error)
描述： 获取用户命中的特定实验的变体详情
参数：
experimentId：指定分流的实验Id
decisionId：本地分流用户标识
attributes：用户属性
返回值： 该函数返回用户命中某个实验的变体详情，通常仅能命中一个变体
返回值示例：

{
    "1324": {
       "val": "3",
       "vid": "27028"
    },
    "father_code": {
       "val": "father_code_2",
       "vid": "27028"
    },
    "grey_rollout": {
        "val": false,
        "vid": "27028"
    },
    "os_name": {
         "val": "android_f",
         "vid": "27028"
     }
 }

3.6 GetAllExperimentConfigs

接口： func (t *AbClient) GetAllExperimentConfigs(decisionId string, attributes map[string]interface{}) (map[string]map[string]interface{}, error)
描述： 获取用户命中的所有实验的变体详情
参数：
decisionId：本地分流用户标识
attributes：用户属性
返回值： 该函数返回用户命中所有实验的变体详情，通常命中多个变体
返回值示例：
与GetExperimentConfigs返回结构相同

3.7 GetFeatureConfigs

接口： func (t *AbClient) GetFeatureConfigs(featureId, decisionId string, attributes map[string]interface{}) (map[string]map[string]interface{}, error)
描述： 获取用户命中的特定feature的变体详情
参数：
featureId：feature Id
decisionId：本地分流用户标识
attributes：用户属性
返回值： 该函数返回用户命中某个feature的变体详情，通常仅能命中一个变体
返回值示例：

{
   "feature_key":{
        "val" : "prod",
        "vid" : "20006421"
    }
}

3.8 GetAllFeatureConfigs

接口： func (t *AbClient) GetAllFeatureConfigs(decisionId string, attributes map[string]interface{}) (map[string]map[string]interface{}, error)
描述： 获取用户命中的所有feature的变体详情
参数：
decisionId：本地分流用户标识
attributes：用户属性
返回值： 该函数返回用户命中所有feature的变体详情，通常命中多个变体
返回值示例：
与GetFeatureConfigs返回结构相同

3.9 GetExperimentVariantNameWithImpression

同接口“GetExperimentVariantName”（上报曝光事件）

3.10 GetAllExperimentConfigsWithImpression

同接口“GetAllExperimentConfigs”（上报曝光事件）

3.11 GetExperimentConfigsWithImpression

同接口“GetExperimentConfigs”（上报曝光事件）

3.12 GetFeatureConfigsWithImpression

同接口“GetFeatureConfigs”（上报曝光事件）

4. 其他

4.1 UserAbInfoHandler

用户信息处理接口，冻结实验、进组不出组场景下使用

说明

冻结实验和进组不出组需要持久化用户的进组信息，SDK提供的默认实现不进行数据持久化；
如有业务需要，则实现UserAbInfoHandler接口，结合Redis或其他外部存储对用户进组信息进行持久化处理，初始化AbClient时传入。
使用方式：

使用NewClient初始化AbClient时默认使用空实现，不启用“进组不出组”功能
继承UserAbInfoHandler接口，自行实现持久化存储；使用NewClientWithUserAbInfo初始化AbClient，并传入自行实现的UserAbInfoHandler类，则可启用“进组不出组”功能

使用Redis缓存示例（仅供参考）

client.NewClientWithUserAbInfo("token", NewRedisUserAbInfoHandler())

type RedisAbInfoHandler struct{}

func (u *RedisAbInfoHandler) Query(decisionID string) string {
    // need to implement it yourself
    return redis.get(decisionID);
}

func (u *RedisAbInfoHandler) CreateOrUpdate(decisionID, experiment2Variant string) bool {
    // need to implement it yourself
    return redis.set(decisionID, experiment2Variant);
}

func (u *RedisAbInfoHandler) NeedPersistData() bool {
    // return true if customize this interface
    return true
}

func NewRedisUserAbInfoHandler() *RedisAbInfoHandler {
        return &RedisAbInfoHandler{}
}

4.2 匿名上报

获取不到uuid的用户，可以通过填充device_id或者web_id进行事件上报

NewClient时设置匿名上报配置，第一个参数（true/开启，false/关闭）匿名上报，第二个参数（true/saas，false/私有化）

client.NewClient("appKey", config.WithAnonymousConfig(true, true))

添加device_id, web_id, bddid到用户属性attributes，trackId固定传入空字符串""

trackId = "";
attributes["device_id"] = 1234; int64
attributes["web_id"] = 5678; int64
attributes["bddid"] = "91011"; string

请求Activate或其他'WithImpression'接口即可匿名上报