简易用户关联 API（IDM2.0-Golang）

用户关联

在服务端应用中，神策分析也要求为每个事件设置用户的 Distinct ID，这有助于神策分析提供更准确的留存率等数据。对于注册用户，推荐使用系统中的用户 ID 作为 Distinct ID，不建议使用用户名、Email、手机号码等可以被修改的信息。

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

用户注册/登录

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

接口

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

示例

// 匿名 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 关联的方法。更详细的说明请参考标识用户，并在必要时联系我们的技术支持人员。

设置用户属性

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

记录用户属性

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

接口

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

示例

distinct_id := "ABCDEF123456789"

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

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

对于不再需要的用户属性，可以通过 ProfileUnset() 接口将属性删除。用户属性中，属性名称与属性值的约束条件与事件属性相同，详细说明请参考数据格式。

记录初次设定的属性

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

接口

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

示例

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)

数值类型的属性

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

接口

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

示例

distinct_id := "ABCDEF123456789"

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

列表类型的属性

对于用户喜爱的电影、用户点评过的餐厅等属性，可以记录列表型属性。需要注意的是，列表型属性中的元素必须为 string 类型，且元素的值会自动去重。关于列表类型限制请见数据格式属性长度限制。

接口

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

示例

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)

埋点事件采集

在 SDK 初始化完成之后，您可以通过以下接口进行数据埋点。

追踪事件

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

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

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

接口

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

示例

distinct_id := "ABCDEF123456"

properties := map[string]interface{}{
    // "$time" 属性是系统预置属性，取值为 int64 类型，表示事件发生的时间，单位毫秒，如果设置该属性，则替换 SDK 内部获取的系统当前时间。如果不填入该属性，则默认使用系统当前时间
    "$time" : time.Now().UnixMilli(),
    // "$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)