You need to enable JavaScript to run this app.
最新活动
产品
解决方案
定价
合作与生态
支持与服务
开发者
了解我们
导航

Golang SDK

更新时间:2023.05.04 18:04:29

1. 集成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.14

2. SDK 上报模式介绍

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

  • HTTP 模式,使用范围广,部署简单,QPS 高。SDK 直接通过http接口进行上报。

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

模式使用场景部署复杂性可靠性上报性能备注

HTTP

绝大多数场景都可以使用,如果跨网络时延比较高,可以使用批量方式。

简单

高,支持批量上报

可以参考 “最佳实践”-->"查看上报时延"章节内容来查看上报的时延。

FILE

不推荐

复杂

很高

低,写文件之后还需要使用logagent来进行上报

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

3. SDK 初始化

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

  • domain

    • SaaS版国内站:https://mcs.ctobsnssdk.com

    • SaaS版国际站: https://mcs.tobsnssdk.com

    • SaaS云原生版:https://gator.volces.com

  • openapiConfig: openapi配置,如果在saas上需要进行item和用户属性上报,需要配置,其他情况不需要进行配置

    • openapiConfig.domain: openapi的域名

      • SaaS版国内站: https://analytics.volcengineapi.com

      • SaaS版国际站: https://analytics.byteplusapi.com

      • SaaS云原生版: https://analytics.volcengineapi.com

    • openapiConfig.ak:openapi的ak, 请联系客户经理获取

    • openapiConfig.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

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.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.3 SDK 配置参考

配置模块配置项含义备注

sdk

mode

上报模式(不区分大小写):http、file。

env枚举类型,saas 表示云上,pri表示私有化,saas_native 表示云原生,非必须,sdk可以根据配置自动判定。

logLevel

日志级别,默认是trace。支持配置:
trace, debug, info, warn, error, fatal

asynroutine异步协程池核心协程数,默认是20。
queueSize异步队列大小,默认是10240。

http

addr

DataFinder 的域名或者ip,支持http和https,例如为 https://{具体域名地址}
在SaaS环境中需要修改成对应的域名:

在SaaS云原生环境中配置为:

  • https://gator.volces.com

headers.Host

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

在SaaS上不需要进行配置。Host 没有 http:// 、https://。

timeouthttp 超时时间。

batch

enable

boolean类型,表示是否开启批量上报。默认是false,不使用批量。

只支持http模式,且SaaS暂不支持批量上报。

size批量上报的数量。
waitTimeMs批量上报,不足batchSize的时候,最大等待时间。

file

path

保存日志的文件目录,需要保证文件的写权限,默认是
logs/datarangers.log。

file 模式下的配置;http 模式下,上报失败的报文记录在 errPath 下。

maxSize单个文件最大数量,默认是100m。
maxBackup最大备份文件数量,默认是0,表示会保留所有文件。
maxAge最大保存的天数,默认是0,表示会保留所有文件。

errPath

上报失败保存日志的文件目录,需要保证文件的写权限,默认是
logs/error-datarangers.log。

openapi

addr

  • openapi的域名
    • SaaS版国内站: https://analytics.volcengineapi.com

    • SaaS版国际站: https://analytics.byteplusapi.com

    • SaaS云原生版:https://analytics.volcengineapi.com

如果在SaaS上需要进行item和用户属性上报,需要配置openapi,其他情况不需要进行配置。

akopenapi的ak,请联系客户经理获取。
skopenapi的sk,请联系客户经理获取。

-

appKeys

SaaS以及SaaS云原生环境,上报设置的appkeys,可以设置多个。多个可以的方式为:

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的方式进行上报。

4 使用SDK

使用前,需要先初始化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)

5 注意事项
  1. 如果服务端能够获取到client_ip,device_model等用户的设备信息,可以使用入参为Header的接口上报。否则默认情况下,对于事件的公共属性均为null或unknown。

  2. SaaS 上用户属性需要先在系统中创建之后再上报,参考<<User Profile API (服务端-SaaS)>>

  3. Item属性需要先在系统中创建之后再上报,参考<<业务对象(Item)数据接入(SaaS查看)>>