Golang SDK

Golang SDK 已经开源，开源地址为： datarangers-sdk-go。建议使用最新版本。${version} 表示 SDK 的版本号。
下载 SDK：

go get github.com/volcengine/datarangers-sdk-go

或者更新本地的 SDK：

go get -u github.com/volcengine/datarangers-sdk-go

或者在go.mod里面添加sdk 依赖：

require (
   github.com/volcengine/datarangers-sdk-go ${version}
)

如果 ${version} 没有传，表示最新的版本。
go 版本要求 >=1.17

增长分析的 SDK 支持多种上报模式，需要先选择使用模式。

• HTTP 模式，使用范围广，部署简单，QPS 高。SDK 直接通过http接口进行上报。
• FILE 模式 (只支持私有化)，部署复杂，需要在服务器上多部署logagent进程服务。由 SDK 先将文件写到本地磁盘，然后通过logagent监听磁盘文件，由logagent使用http接口进行上报。

推荐使用 HTTP 的方式，同时使用 logagent 来补报因为网络抖动等原因导致失败的数据。

SDK 使用前需要先初始化，然后使用其提供的接口进行上报。

3.1 使用配置文件进行初始化

推荐使用配置的方式进行初始化

package main

import (
   // 引入 sdk
   sdk "github.com/volcengine/datarangers-sdk-go"
)

func main() {
   // 初始化, YAML_PATH 替换成真实的配置文件
   sdk.InitByFile("{YAML_PATH}")
   
   //... 接口调用 
   
   // 避免程序立刻退出
   time.Sleep(60 * time.Second)
}

3.1.1 HTTP 模式

需要配置sdk.mode=http

3.1.1.1 SAAS 配置

sdk:
  mode: http
#  logLevel: debug
http:
  addr: https://mcs.ctobsnssdk.com # 国内地址，国际: https://mcs.tobsnssdk.com
appKeys:
  ${APP_ID}: ${APP_KEY}
openapi:
  addr: https://analytics.volcengineapi.com # 国内地址，国际: https://analytics.byteplusapi.com
  ak: ${OPENAPI_AK}
  sk: ${OPENAPI_SK}
#asyn:
#  routine: 20   #建议小于1024，并发数目
#  queueSize: 10240

• http.addr
  • SaaS版国内站：https://mcs.ctobsnssdk.com
  • SaaS版国际站: https://mcs.tobsnssdk.com
• openapi: openapi配置，如果在saas上需要进行item和用户属性上报，需要配置；云原生和私有化不需要进行配置
  • openapi.addr： openapi的域名
    • SaaS版国内站: https://analytics.volcengineapi.com
    • SaaS版国际站: https://analytics.byteplusapi.com
  • openapi.ak: openapi的ak， 请联系客户经理获取
  • openapi.sk: openapi的sk ，请联系客户经理获取

3.1.1.2 私有化配置

sdk:
  mode: http
#  logLevel: debug
http:
  addr: ${SDK_DOMAIN} #上报的IP 或 域名，注意加上 http://，或者https://
  headers:
    Host: ${SDK_HOST} # host，私有化环境Host的配置在安装部署的那台机器上，查看/home/{INSTALL_USER}/DataRangersDeploy/conf_rangers.yml中配置项sdk.report.host。 INSTALL_USER 为安装用户，一般是datarangers或者minibase
#  timeout: 30 # secenods
#asyn:
#  routine: 20   #建议小于1024，并发数目
#  queueSize: 10240

如果跨网络时延比较大、或者追求更高的QPS，可以开启批量上报的方式。

batch:
  enable: true
#  size: 20
#  waitTimeMs: 100

• Host: datarangers.sdk.headers为http请求中headers字段内容,在私有化环境中必须要添加Host，在私有化环境Host的配置在安装部署的那台机器上，查看/home/{INSTALL_USER}/DataRangersDeploy/conf_rangers.yml中配置项sdk.report.host。 INSTALL_USER 为安装用户，一般是datarangers或者minibase。

3.1.1.3 SAAS 云原生配置

sdk:
  mode: http
  env: saas_native # 设置环境信息为 SaaS 云原生
#  logLevel: debug
http:
  addr: https://gator.volces.com  #上报的IP 或 域名
appKeys:
  ${APP_ID}: ${APP_KEY}
#asyn:
#  routine: 20   #建议小于1024，并发数目
#  queueSize: 10240

云原生的 http.addr 地址为 https://gator.volces.com

3.1.2 FILE 模式

该模式只在私有化支持
设置sdk.mode=file

sdk:
  mode: file
#  logLevel: debug
file:
  path: logs1/datarangers.log
  errPath: logs1/error-datarangers.log
#  maxSize: 100     #Mb
#  maxBackups: 0 #日志最多保存数目
#  maxAge: 0  #days
#asyn:
#  routine: 20   #建议小于1024，并发数目
#  queueSize: 10240

使用该模式，埋点事件只是记录到磁盘中，还需要配合logagent一起使用，数据才能上报到 DataFinder，关于logagent的使用，请联系客户经理获取。

3.1.3 KAFKA 模式

该模式只在私有化支持
设置sdk.mode=kafka

sdk:
  mode: kafka
kafka:
#  kafka brokers，如果有多个，则配置多个
  kafka_brokers:
    - 127.0.0.1:9192

3.2 直接在程序中进行初始化

自定义sdk.SysConf，然后进行初始化

package main

import (
   sdk "github.com/volcengine/datarangers-sdk-go"
)

func main() {
   // 初始化，设置相关参数
   sysconf := &sdk.SysConf{
      ... 
   }
   sdk.InitBySysConf(sysconf)

   // 避免程序立刻退出
   time.Sleep(60 * time.Second)
}

3.2.1 HTTP 模式

3.2.1.1 SaaS 初始化

import (
   sdk "github.com/volcengine/datarangers-sdk-go"
)

appId, _ := strconv.Atoi(os.Getenv("SDK_APP_1"))
sysconf := &sdk.SysConf{
   // 设置模式
   SdkConfig: sdk.SdkConfig{
      Mode: sdk.MODE_HTTP,
   },
   // 设置domain和appKey, 不需要设置HOST
   HttpConfig: sdk.HttpConfig{
      HttpAddr: "https://mcs.ctobsnssdk.com",
   },
   // 可以设置多个app，这里注意替换成真实的参数
   AppKeys: map[int64]string{
      int64(appId): os.Getenv("SDK_APP_KEY_1"),
   },
   // 设置openapi domain, AK,SK，这里注意替换成真实的参数
   OpenapiConfig: sdk.OpenapiConfig{
      HttpAddr: "https://analytics.volcengineapi.com",
      Ak:       os.Getenv("OPENAPI_AK"),
      Sk:       os.Getenv("OPENAPI_SK"),
   },
}
sdk.InitBySysConf(sysconf)

3.2.1.2 私有化初始化

import (
   sdk "github.com/volcengine/datarangers-sdk-go"
)

sysconf := &sdk.SysConf{
   // 设置模式
   SdkConfig: sdk.SdkConfig{
      Mode: sdk.MODE_HTTP,
   },
   // 设置domain和host，这里注意替换成真实的参数
   HttpConfig: sdk.HttpConfig{
      HttpAddr: os.Getenv("SDK_DOMAIN"),
      Headers: map[string]interface{}{
         "Host": os.Getenv("SDK_HOST"),
      },
   },
}
sdk.InitBySysConf(sysconf)

3.2.1.3 SaaS 云原生初始化

import (
   sdk "github.com/volcengine/datarangers-sdk-go"
)

sysconf := &sdk.SysConf{
   // 设置模式
   SdkConfig: sdk.SdkConfig{
      Mode: sdk.MODE_HTTP,
      Env:  sdk.ENV_SAAS_NATIVE,
   },
   // 设置domain和appKey, 不需要设置HOST
   HttpConfig: sdk.HttpConfig{
      HttpAddr: "https://gator.volces.com",
   },
   // 可以设置多个app，这里注意替换成真实的参数
   AppKeys: map[int64]string{
      int64(appId): os.Getenv("SDK_APP_KEY_1"),
   },
}
sdk.InitBySysConf(sysconf)

3.2.2 FILE 模式

该模式只在私有化支持
设置sdk.mode=file

import (
   sdk "github.com/volcengine/datarangers-sdk-go"
)

sysconf := &sdk.SysConf{
   // 设置模式
   SdkConfig: sdk.SdkConfig{
      Mode: sdk.MODE_FILE,
   },
   // 配置保存的路径
   FileConfig: sdk.FileConfig{
      Path:    "logs/datarangers.log",
      ErrPath: "logs/error-datarangers.log",
   },
}
sdk.InitBySysConf(sysconf)

3.2.2 KAFKA 模式

该模式只在私有化支持
设置sdk.mode=kafka

import (
    sdk "github.com/volcengine/datarangers-sdk-go"
)

func main() {
    // 初始化
    sdk.InitBySysConf(&sdk.SysConf{
       // 设置模式
       SdkConfig: sdk.SdkConfig{
          Mode: sdk.MODE_KAFKA,
       },
       // 设置domain和host，这里注意替换成真实的参数
       KafkaConfig: &sdk.KafkaConfig{
          KafkaBrokers: []string{os.Getenv("SDK_KAFKA_BROKER_1"), os.Getenv("SDK_KAFKA_BROKER_2")},
       },
    })
}

3.3 SDK 配置参考

appKeys:
  ${APP_ID_1}: ${APP_KEY_1}
  ${APP_ID_2}: ${APP_KEY_2}

3.4 验证配置

3.4.1 查看启动日志

启动会打印如下日志，可以通过监测启动日志来确定配置是否符合预期。主要关注下SdkConfig.Mode``，``HttpConfig 等配置。

[DEBUG:]2023/02/27 15:54:20 user config :{"SdkConfig":{"Mode":"file","Env":"pri","LogLevel":""},"BatchConfig":{"Enable":false,"Size":0,"WaitTimeMs":0},"FileConfig":{"EventSendEnable":false,"Path":"logs/datarangers.log","MaxSize":100,"MaxBackup":0,"MaxAge":0,"ErrPath":"logs/error-datarangers.log"},"HttpConfig":{"HttpAddr":"","SocketTimeOut":0,"Headers":null},"AsynConfig":{"Routine":20,"QueueSize":10240},"OpenapiConfig":{"HttpAddr":"","Ak":"","Sk":""},"VerifyConfig":{"Url":""},"AppKeys":null}

3.4.2 HTTP 模式

参考 “JAVA SDK” 文档中，“验证配置”中的 HTTP 模式方式。

3.4.3 FILE 模式 （只支持私有化）

查看配置 file.path 的文件目录下是否有文件，是否有文件内容。校验文件内容是否正确，可以直接拷贝一行数据，使用http的方式进行上报。

3.4.4 KAFKA 模式 (只支持私有化)

查看kafka topic: sdk_origin_event 是否有数据上来，kafka 的使用方式参考文档：
Kafka订阅(私有化) 增长分析-火山引擎

使用前，需要先初始化sdk，初始化参考“SDK 初始化”，初始化之后就可以使用接口进行上报了。

4.1 接口

// SendEvent
// eventParam : 事件属性
// custom     : 用户自定义事件公共属性
// Deprecated: instead of SendEventInfo
func SendEvent(appType AppType, appid int64, uuid string, eventname string, eventParam map[string]interface{}, custom map[string]interface{}, did ...int64) error

// SendEventInfo 上报事件信息
// event: 事件信息
// custom: 事件公共属性
func SendEventInfo(appType AppType, appId int64, uuid string, event *EventV3, custom map[string]interface{}) error

// SendEventInfoWithItem 上报携带item的事件
// event: 事件信息
// custom: 事件公共属性
// itemList: item 信息
func SendEventInfoWithItem(appType AppType, appId int64, uuid string, event *EventV3, custom map[string]interface{}, itemList []*Item) error

// SendEventInfos 上报多个事件
// events: 事件信息
// custom: 事件公共属性
func SendEventInfos(appType AppType, appId int64, uuid string, events []*EventV3, custom map[string]interface{}) error

// SendEventWithHeader 使用header上报事件
// header: 事件的header
// event: 事件信息
func SendEventWithHeader(appType AppType, appId int64, hd *Header, event *EventV3) error

// SendProfile
// profileAction ：用户公共属性操作类型
// profileParam :  用户公共属性
func SendProfile(apptype AppType, appid int64, uuid string, profileAction ProfileActionType, profileParam map[string]interface{}, did ...int64) error 

// ItemSet 设置item 属性
// itemName: item 名称
// itemParamList: item 属性信息
func ItemSet(appid int64, itemName string, itemParamList []map[string]interface{}) error

4.2 SDK DEMO

参考代码：
https://github.com/volcengine/datarangers-sdk-go/tree/release/v2.0.1/_example

4.3 发送普通事件

// 应用id
appId := {APP_ID}
// 用户id
uuid := {uuid}
// 事件公共属性，如果不需要的话，可以传nil
commonParams := map[string]interface{}{
   "common_string1": "common_value1",
   "common_int1":    13,
}
eventName := "app_send_event_info"
eventV3 := &sdk.EventV3{
   Event:       eventName,
   Params: map[string]interface{}{
      "app_send_event_param1": "value1",
      "app_send_event_param2": "value2",
   },
}
sdk.SendEventInfo(sdk.APP, appId, uuid, eventV3, commonParams)

4.4 设置用户属性

// 应用id
appId := example.AppId
// 用户id
uuid := example.Uuid
// 用户属性
properties := map[string]interface{}{
   "list":      []string{"a"},
   "profile_a": "param_11",
}

sdk.ProfileSet(sdk.APP, appId, uuid, properties)

4.5 设置item属性

// 应用id
appId := example.AppId

// item属性
itemParamList := []map[string]interface{}{
   {"id": 121, "category": "economics"},
   {"id": 122, "category": "literature"},
   {"id": 123, "category": "fiction"},
   {"id": 124, "category": "fiction"},
   {"id": 125, "category": "fiction"},
}

err := sdk.ItemSet(appId, "book", itemParamList)

4.6 发送携带item的时间

// 应用id
appId := {APP_ID}
// 用户id
uuid := {uuid}
// 事件公共属性，如果不需要的话，可以传nil
commonParams := map[string]interface{}{
   "common_string1": "common_value1",
   "common_int1":    13,
}
eventName := "app_send_event_info"
// 事件发生时间
localTimeMs := time.Now().UnixMilli()
eventV3 := &sdk.EventV3{
   Event:       eventName,
   LocalTimeMs: &localTimeMs,
   Params: map[string]interface{}{
      "app_send_event_param1": "value1",
      "app_send_event_param2": "value2",
   },
}
sdk.SendEventInfo(sdk.APP, appId, uuid, eventV3, commonParams)

1. 如果服务端能够获取到client_ip，device_model等用户的设备信息，可以使用入参为Header的接口上报。否则默认情况下，对于事件的公共属性均为null或unknown。
2. SaaS 上用户属性需要先在系统中创建之后再上报，参考<<User Profile API (服务端-SaaS)>>
3. Item属性需要先在系统中创建之后再上报，参考<<业务对象（Item）数据接入（SaaS查看）>>
4. 如果使用 v1.1.0，v1.1.1，v1.1.2 这3个版本上报过用户属性，需要处理；如果只是上报事件，那么不需要处理：
   a. 不影响事件上报，只影响用户属性
   b. 如果 SDK 不升级到最新的版本，且没有通过其他方式来上报用户属性，可以不用处理；
   c. 如果 SDK 需要升级到最新的版本 >=v1.1.3,或者使用其他方式上报数据，在升级前需要联系客户经理处理下数据，否则会导致新的用户属性上报不生效。