集成文档（Golang）

Golang SDK 使用说明

在使用前，请先阅读数据模型 的介绍。

集成神策分析 SDK

在 Golang 代码中集成神策分析 SDK，使用神策分析采集并分析用户数据。

我们推荐 Golang 官方工具管理 Golang 项目并获取神策分析 SDK：

go get github.com/sensorsdata/sa-sdk-go

或更新本地已经存在的sdk:

go get -u github.com/sensorsdata/sa-sdk-go

也可以从 GitHub 下载神策分析 SDK 的源代码。

SDK 需要 Golang 1.6 以上，不依赖第三方库。目前 Golang SDK 不支持 Windows。

初始化神策分析 SDK

获取配置信息

首先从神策分析的主页中，获取数据接收的 URL 和 Token（Cloud 版）。

在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例，下面以 ConcurrentLoggingConsumer 为例：

import sdk "github.com/sensorsdata/sa-sdk-go"

// 从神策分析配置页面中获取数据接收的 URL
SA_SERVER_URL := "YOUR_SERVER_URL"

// 初始化一个 Consumer，用于数据发送
consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", true)
//...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()

properties := map[string]interface{}{
        "price": 12,
        "name": "apple",
}

// 记录用户事件
err = sa.Track("ABCDEFG1234567", "ViewProduct", properties, false)

用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 Close() 方法显式关闭，否则可能丢失部分缓存的数据。

使用神策分析时，引入神策分析 SDK 后首先初始化一个 consumer，接着初始化神策分析对象。

初始化神策分析对象的接口为：

// c 为 consumer，projectName 为项目名，timeFree 为是否导入历史数据
// 默认情况下，神策会过滤发生时间比较久远数据（例如 10 天之前，具体取决于服务端设置），如果想导入历史数据，可以通过开启 timeFree 选项来绕过这个限制。
func InitSensorsAnalytics(c consumers.Consumer, projectName string, timeFree bool) SensorsAnalytics

示例

sa := sdk.InitSensorsAnalytics(consumer, "default", false)
// 退出函数前调用 Close，回收资源，发送缓存中的数据
defer sa.Close()
// ...

至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的控制神策分析 SDK 一节。

设置神策分析 SDK

Golang SDK 主要由以下两个组件构成:

SensorsAnalytics：用于发送数据的接口对象，构造函数需要传入一个 Consumer 实例
Consumer：Consumer 会进行实际的数据发送

为了让开发者更灵活的接入数据，神策分析 SDK 实现了以下 Consumer：

LoggingConsumer
ConcurrentLoggingConsumer
DebugConsumer
DefaultConsumer
BatchConsumer

LoggingConsumer（推荐）

用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件并使用 LogAgent 等工具导入。

初始化接口

// filename 为输出文件前缀，hourRotate 为是否按小时切割
func InitLoggingConsumer(filename string, hourRotate bool) (*consumers.LoggingConsumer, error)

例子

import sdk "github.com/sensorsdata/sa-sdk-go"

// 初始化 LoggingConsumer
consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", false)
// ...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()

// ...

LoggingConsumer 的第一个参数是保存文件前缀，第二个参数表示是否启用按小时切割，默认是每天 0 点切割保留所有文件。

按小时切割关闭的情况下，文件将保存在以 prefix.YYYY-MM-DD（例如：假设 prefix 为 /data/sa/access.log，当天是 2018-04-13，则输出文件为 /data/sa/access.log.2018-03-13）
按小时切割开启的情况下，在小时整点切割，文件将保存在以 prefix.YYYY-MM-DD.H（例如：假设 prefix 为 /data/sa/access.log，当天是 2018-04-13 14 点，则输出文件为 /data/sa/access.log.2018-03-13.14）

// 按小时切分
consumer, err := sdk.InitLoggingConsumer("/data/sa/access.log", true)

注意，请不要使用多进程写入同一个日志文件，可能会造成数据丢失或者错乱。如果需要多进程写入，请使用 ConcurrentLoggingConsumer。

ConcurrentLoggingConsumer（推荐）

用于将数据输出到指定目录，并自动按天切割文件，支持按小时切割，参数含义同 LoggingConsumer ，与 LoggingConsumer 不同的是，它支持多进程写入同一个文件。

初始化接口

// filename 为输出文件前缀，hourRotate 为是否按小时切割
func InitConcurrentLoggingConsumer(filename string, hourRotate bool) (*consumers.ConcurrentLoggingConsumer, error)

例子

import sdk "github.com/sensorsdata/sa-sdk-go"

// 初始化 ConcurrentLoggingConsumer
consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", true)
// ...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)

// 程序结束前调用 Close() ，让 Consumer 刷新所有缓存数据到文件中
defer sa.Close()

// ...

注意： LogAgent 配置文件中一定要注释掉 real_time_file_name 参数，否则无法正常导入数据。已使用 LoggingConsumer 的客户建议按照如下步骤切换到 ConcurrentLoggingConsumer：

第 1 步停掉 LogAgent，并注释掉 LogAgent 配置中的 real_time_file_name 参数。
第 2 步将日志目录下的 real_time_file_name 的文件加上当前时间的后缀 ".YYYY-MM-DD"。
第 3 步后端程序升级切换到 ConcurrentLoggingConsumer。
第 4 步重新启动 LogAgent。

DebugConsumer（测试使用）

用于校验数据导入是否正确，关于 Debug 调试模式的详细信息，请进入相关页面查看。请注意：Debug 模式是为方便开发者调试而设置的模式，该模式会逐条校验数据并在校验失败时抛出异常，性能远低于正常模式。线上环境使用 Debug 模式会严重影响性能并存在崩溃风险，产品上线前请务必替换掉/关闭 Debug 模式。

初始化接口为

// url是接收端url，writeData表示是否校验数据，timeout是发送超时时间，单位是毫秒
// writeData为
//   true - 校验数据，并将数据导入到神策分析中
//   false - 校验数据，但不进行数据导入
func InitDebugConsumer(url string, writeData bool, timeout int) (*consumers.DebugConsumer, error)

例子

import sdk "github.com/sensorsdata/sa-sdk-go"

// 神策分析数据接收的 URL
SA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
SA_REQUEST_TIMEOUT := 100000
// Debug 模式下，是否将数据导入神策分析
//   true - 校验数据，并将数据导入到神策分析中
//   false - 校验数据，但不进行数据导入
SA_DEBUG_WRITE_DATA := true

// 初始化 Debug Consumer
consumer, err := sdk.InitDebugConsumer(SA_SERVER_URL, SA_DEBUG_WRITE_DATA, SA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()

// ...

DefaultConsumer

通常用于导入小规模历史数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。普通 Consumer，实现，逐条、同步的发送数据给接收服务器。

初始化接口

// url 是接收端 URL，timeout 是发送超时时间，单位是毫秒
func InitDefaultConsumer(url string, timeout int) (*consumers.DefaultConsumer, error)

例子

import sdk "github.com/sensorsdata/sa-sdk-go"

// 神策分析数据接收的 URL
SA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
SA_REQUEST_TIMEOUT := 100000

// 初始化 Default Consumer
consumer, err := sdk.InitDefaultConsumer(SA_SERVER_URL, SA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()

// ...

BatchConsumer

通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是网络直接发送数据，如果网络出现异常可能会导致数据重发或丢失，因此不要用在任何线上服务中。批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。

初始化接口

// url是接收端url，max是最大缓存条数，timeout是发送超时时间，单位是毫秒
func InitBatchConsumer(url string, max, timeout int) (*consumers.BatchConsumer, error)

例子

import sdk "github.com/sensorsdata/sa-sdk-go"

// 神策分析数据接收的 URL
SA_SERVER_URL := "YOUR_SERVER_URL"
// 发送数据的超时时间，单位毫秒
SA_REQUEST_TIMEOUT := 100000
// 当缓存的数据量达到参数值时，批量发送数据
SA_BULK_SIZE := 100

// 初始化 Batch Consumer
consumer, err := sdk.InitBatchConsumer(SA_SERVER_URL, SA_BULK_SIZE, SA_REQUEST_TIMEOUT)
// ...
// 使用 Consumer 来构造 SensorsAnalytics 对象
sa := sdk.InitSensorsAnalytics(consumer, "default", false)
defer sa.Close()

// ...

API 接口

针对 API 接口的使用文档，参照基础 API 使用文档介绍。