# Golang SDK

> *在使用前，请先阅读*[*数据模型*](https://54td.gitbook.io/shence/technical_guide/data_import/data_model)*的介绍。*

## 1. 集成神策分析 SDK

在 Golang 代码中集成 [神策分析 SDK](https://github.com/sensorsdata/sa-sdk-go)，使用神策分析采集并分析用户数据。

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

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

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

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

也可以从 Github 下载 [神策分析 SDK](https://github.com/sensorsdata/sa-sdk-go) 的源代码。

SDK 需要 Golang 1.6以上，不依赖第三方库。

* 目前golang sdk不支持windows

## 2. 初始化神策分析 SDK

### 2.1 获取配置信息

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

![](https://3928609189-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-Levm4x0IpHBx6dxiaCM%2F-LeydYULqjq7WfRLX0IT%2F-Leydck2ctJbhNeQRsjz%2Fmulti_project_data_api.png?generation=1557976757617660\&alt=media)

如果使用神策分析 Cloud 服务，需获取的配置信息为:

* 数据接收地址，建议使用不带端口号的: <http://{$service_name}.datasink.sensorsdata.cn/sa?project={$project_name}&token={$project_token}>
* 数据接收地址，带端口号的: <http://{$service_name}.cloud.sensorsdata.cn:8106/sa?project={$project_name}&token={$project_token}>

如果用户使用单机版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

  （注：神策分析 1.7 及之前的版本，单机版私有部署默认端口号为 8006）

如果用户使用集群版私有部署的神策分析，默认的配置信息为：

* 数据接收地址: <http://{$host_name}:8106/sa?project={$project_name}>

其中 `{$host_name}` 可以是集群中任意一台机器。

如果私有部署的过程中修改了 Nginx 的默认配置，或通过 CDN 等访问神策分析，则请咨询相关人员获得配置信息。

### 2.2 在程序中初始化 SDK

在程序中初始化的代码段中构造神策分析 SDK 的实例：

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

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

    // 初始化一个 Consumer，用于数据发送
    // DefaultConsumer 是同步发送数据，因此不要在任何线上的服务中使用此 Consumer
    consumer, err := sdk.InitDefaultConsumer(SA_SERVER_URL, 10000)
    //...
    // 使用 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)
```

其中 `YOUR_SERVER_URL` 是前文中从神策分析获取的数据接收的 URL。用户程序应该一直持有该实例，直到程序结束。程序退出前，需要使用 `Close()` 方法显式关闭，否则可能丢失部分缓存的数据。

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

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

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

* 例子

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

至此，我们已经可以正常使用神策分析 SDK 了。需了解更多关于 SDK 的使用方法，可以跳到本文末尾的 [控制神策分析 SDK](#6-设置-sensors-analytics-sdk) 一节。

## 3. 追踪事件

第一次接入神策分析时，建议先追踪 3\~5 个关键的事件，只需要几行代码，便能体验神策分析的分析功能。例如：

* 图片社交产品，可以追踪用户浏览图片和评论事件
* 电商产品，可以追踪用户注册、浏览商品和下订单等事件

用户通过 `Track()` 接口记录事件，对于任何事件，必须包含用户标志符（`distinctId`）和事件名（`event`）两个参数。同时，用户可以在 `Track()` 的第三个参数传入一个 `map[string]interface{}` 对象，为事件添加自定义事件属性。以电商产品为例，可以这样追踪一次购物行为：

* 接口

```go
    //distinctId是用户标示，event是事件名，properties是自定义事件属性，isLoginId表示是否登陆
    func (sa *SensorsAnalytics) Track(distinctId, event string, properties map[string]interface{}, isLoginId bool) error
```

* 例子

```go
    distinct_id := "ABCDEF123456"

    properties := map[string]interface{}{
        // "$time" 属性是系统预置属性，传入 datetime 对象，表示事件发生的时间，如果不填入该属性，则默认使用系统当前时间
        "$time" : time.Now(),
        // "$ip" 属性是系统预置属性，如果服务端中能获取用户 IP 地址，并填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息
        "$ip" : "123.123.123.123",
        // 商品 ID
        "ProductId" : "123456",
        // 商品类别
        "ProductCatalog" : "Laptop Computer",
        // 是否加入收藏夹，Boolean 类型的属性
        "IsAddedToFav" : True,
    }

    // 记录用户浏览商品事件
    err := sa.Track(distinct_id, "ViewProduct", properties, true)

    properties:= map[string]interface{}{
        // 用户 IP 地址
        "$ip" : "123.123.123.123",
        // 商品 ID 列表，[]string 类型的属性
        "ProductIdList" : []string{"123456", "234567", "345678"},
        // 订单价格
        "OrderPaid" : 12.10,
    }

    // 记录用户订单付款事件
    err = sa.Track(distinct_id, "PaidOrder", properties, true)
```

### 3.1 事件属性

如前文中的样例，追踪的事件可以设置自定义的事件属性，例如浏览商品事件中，将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中，事件属性可以作为统计过滤条件使用，也可以作为维度进行多维分析。对于事件属性，神策分析有一些约束:

* 事件属性是一个 `map[string]interface{}` 对象
* `map` 中每个元素描述一个属性，Key 为属性名称，必需是 `string` 类型
* `map` 中，每个元素的 Value 是属性的值，支持 `string`、`int`、`float64`、`[]string`、`time.Time`

对于神策分析中事件属性的更多约束，请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema)

#### 3.1.1 系统预置属性

如前文中样例，事件属性中以 "$" 开头的属性为系统预置属性，在自定义事件属性中填入对应 "$" 开头的属性值可以覆盖这些预置属性：

* `$ip` - 填入该属性，神策分析会自动根据 IP 地址解析用户的省份、城市信息，该属性值为 `string` 类型；
* `$time` - 填入该属性，神策分析将事件时间设置为属性值的时间，该属性值必须为 `time.Time` 。请注意，神策分析默认会过滤忽略 365 天前或 3 天后的数据，如需修改请联系我们。

关于其他更多预置属性，请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema) 中 "预置属性" 一节。

## 4. 用户识别

在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct Id，这有助于神策分析提供更准确的留存率等数据。

对于注册用户，推荐使用系统中的用户 ID 作为 Distinct Id，不建议使用用户名、Email、手机号码等可以被修改的信息。

所有的 Track 和 Profile 系列方法建议明确指定 isLoginId 参数，以便明确告知神策分析用户 ID 的类型。

### 4.1 用户注册/登录

当同一个用户的 Distinct Id 发生变化时（一般情况为匿名用户注册行为），可以通过 `TrackSignup()` 将旧的 Distinct Id 和新的 Distinct Id 关联，以保证用户分析的准确性。

* 接口

```go
    // distinctId 为新的 ID（注册后的 ID），originId 为旧 ID（匿名 ID）
    func (sa *SensorsAnalytics) TrackSignup(distinctId, originId string) error
```

* 例子

```go
    // 匿名 ID 由前端传过来
    anonymous_id := "9771C579-71F0-4650-8EE8-8999FA717761"

    register_id := "0012345678"
    // 用户注册/登录时，将用户注册 ID 与 匿名 ID 关联
    err := sa.TrackSignup(register_id, anonymous_id)
```

注意，对同一个用户，`TrackSignup()` 一般情况下建议只调用一次（通常在用户 **注册** 时调用），用户 **登录** 前后的行为的关联建议在业务端实现。在神策分析 1.13 版本之前，多次调用 `TrackSignup()` 时，只有第一次关联行为是有效的。神策分析 1.13 版本之后提供了多设备 id 关联的方法。更详细的说明请参考 [如何准确的标识用户](https://54td.gitbook.io/shence/technical_guide/data_import/user_identify)，并在必要时联系我们的技术支持人员。

## 5. 设置用户属性

为了更准确地提供针对人群的分析服务，神策分析 SDK 可以设置用户属性，如年龄、性别等。用户可以在留存分析、分布分析等功能中，使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。

使用 `ProfileSet()` 设置用户属性:

* 接口

```go
    // distinctId为用户标示，properties为要设置的用户属性，isLoginId标示distinctId是否为登陆后的id
    func (sa *SensorsAnalytics) ProfileSet(distinctId string, properties map[string]interface{}, isLoginId bool) error
```

* 例子

```go
    distinct_id := "ABCDEF123456789"

    properties := map[string]interface{}{
        // 用户性别属性（Sex）为男性
        "Sex" : "Male",
        // 用户等级属性（Level）为 VIP
        "UserLevel" : "Elite VIP",
    }

    // 设置用户属性
    err := sa.ProfileSet(distinct_id, properties, true)
```

对于不再需要的用户属性，可以通过 `ProfileUnset()` 接口将属性删除。

用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考 [数据格式](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema)。

### 5.1 记录初次设定的属性

对于只在首次设置时有效的属性，我们可以使用 `ProfileSetOnce()` 记录这些属性。与 `ProfileSet()` 接口不同的是，如果被设置的用户属性已存在，则这条记录会被忽略而不会覆盖已有数据，如果属性不存在则会自动创建。因此，`ProfileSetOnce()` 比较适用于为用户设置首次激活时间、首次注册时间等属性。

* 接口

```go
    // distinctId为用户标示，properties为要设置的用户属性，isLoginId标示distinctId是否为登陆后的id
    func (sa *SensorsAnalytics) ProfileSetOnce(distinctId string, properties map[string]interface{}, isLoginId bool) error
```

* 例子

```go
    distinct_id := "ABCDEF123456789"

    // 设置用户渠道属性（AdSource）为 "App Store"
    properties := map[string]interface{}{
        "AdSource" : "App Store",
    }
    err := sa.ProfileSetOnce(distinct_id, properties, true)

    properties = map[string]interface{}{
        "AdSource" : "Search Engine",
    }
    // 再次设置用户渠道属性（AdSource），设定无效，属性 "AdSource" 的值仍为 "App Store"
    err = sa.ProfileSetOnce(distinct_id, properties, true)
```

### 5.2 数值类型的属性

对于数值型的用户属性，可以使用 `ProfileIncrement()` 对属性值进行累加。常用于记录用户付费次数、付费额度、积分等属性。

* 接口

```go
    // distinctId为用户标示，properties为要设置的用户属性，这个属性中应该只包含value为int的属性，isLoginId标示distinctId是否为登陆后的id
    func (sa *SensorsAnalytics) ProfileIncrement(distinctId string, properties map[string]interface{}, isLoginId bool) error
```

* 例子

```go
    distinct_id := "ABCDEF123456789"

    properties := map[string]interface{}{
        "GamePlayed" : 1,
    }
    // 设置用户游戏次数属性（GamePlayed），将次数累加1次
    err := sa.ProfileIncrement(distinct_id, properties, true)
```

### 5.3 列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 `string` 类型，且元素的值会自动去重。关于列表类型限制请见 [**数据格式**](https://54td.gitbook.io/shence/technical_guide/data_import/data_schema) **7.3 属性长度限制**。

* 接口

```go
    // distinctId为用户标示，properties为要设置的用户属性，这个属性中应该只包含value为[]string的属性，isLoginId标示distinctId是否为登陆后的id
    func (sa *SensorsAnalytics) ProfileAppend(distinctId string, properties map[string]interface{}, isLoginId bool) error
```

* 例子

```go
    distinct_id := "ABCDEF123456789"

    properties := map[string]interface{}{
        // 电影列表
        "Movies" : []string{"Sicario", "Love Letter"},
        // 游戏列表
        "Games" : []string{"Call of Duty", "Halo"},
    }

    // 传入properties，设置用户喜欢的电影属性（movies）和喜欢的游戏属性（games）
    // 设置成功后，"Movies" 属性值为 ["Sicario", "Love Letter"]；"Games" 属性值为 ["Call of Duty", "Halo"]
    err := sa.ProfileAppend(distinct_id, properties, true)

    // 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（Movies）
    // 设置成功后 "Movies" 属性值为 ["Sicario", "Love Letter", "Dead Poets Society"]
    properties = map[string]interface{}{
        "Movies" : []string{"Dead Poets Society"},
    }
    err = sa.ProfileAppend(distinct_id, properties, true)

    // 传入属性名称和需要插入属性的值，设置用户喜欢的电影属性（Movies），
    // 但属性值 "Love Letter" 与已列表中已有元素重复，操作无效，
    // "Movies" 属性值仍然为 ["Sicario", "Love Letter", "Dead Poets Society"]
    properties = map[string]interface{}{
        "Movies" : []string{"Love Letter"},
    }
    err = sa.ProfileAppend(distinct_id, properties, true)
```

## 6. 设置神策分析 SDK

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

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

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

### 6.1 LoggingConsumer(推荐)

用于将数据输出到指定目录并按天切割文件，支持通过参数指定是否按小时切割，一般用来处理实时数据，生成日志文件并使用 [LogAgent](https://54td.gitbook.io/shence/technical_guide/import_tool) 等工具导入。

* 初始化接口

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

* 例子

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

    // 初始化 Logging Consumer
    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）

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

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

### 6.2 ConcurrentLoggingConsumer（推荐）

* ConcurrentLoggingConsumer不支持windows，windows下请使用LoggingConsumer

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

* 初始化接口

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

* 例子

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

    // 当缓存的数据量达到参数值时，批量向文件中写入数据
    SA_BULK_SIZE := 1024

    // 初始化 Concurrent Logging Consumer，写入文件 "/data/sa/access.log.YYYY-MM-DD" 中，日志缓冲区长度为 1024 条
    consumer, err := sdk.InitConcurrentLoggingConsumer("/data/sa/access.log", SA_BULK_SIZE)
    // ...
    // 使用 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。

### 6.3 DebugConsumer（测试使用)

用于校验数据导入是否正确，关于 [Debug 模式](https://54td.gitbook.io/shence/technical_guide/data_import/debug_mode) 的详细信息，请进入相关页面查看。请注意，*不要在生产环境中使用 Debug 模式*。

* 初始化接口为

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

* 例子

```go
    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()

    // ...
```

### 6.4 DefaultConsumer

**通常用于导入小规模历史数据。由于是同步发送数据，因此不要用在任何线上的服务中。** 普通 Consumer，实现，逐条、同步的发送数据给接收服务器。

* 初始化接口

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

* 例子

```go
    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()

    // ...
```

### 6.5 BatchConsumer

**通常用于导入小规模历史数据，或者离线 / 旁路导入数据的场景。由于是同步发送数据，因此不要用在任何线上的服务中。** 批量发送数据的 Consumer，当且仅当数据达到指定的量时，才将数据进行发送。

* 初始化接口

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

* 例子

```go
    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()

    // ...
```