概述

Gravity Engine Go SDK 是一个用于数据采集和上报的工具，帮助开发者轻松集成事件追踪和用户行为分析功能。本SDK兼容Golang 1.25.5 及以上版本。在接入前, 请先阅读接入前准备。

服务端接入GO SDK，完成事件的服务端报送功能，您需要注意以下几点：

服务端SDK仅负责事件的收集上报，不负责用户的注册，用户注册需要调用客户端 SDK 的 initialize 方法完成；
客户端和服务端SDK使用的用户 client id 需要保持一致；
在客户端完成 initialize 方法调用之后，服务端SDK才能开始做事件采集上报，否则上报不成功；
服务端SDK接入事件上报时，请参考元事件页面下关于事件的详情属性；
请尽量上报事件的公共属性，引力不做强制要求，但是上报足够多属性，可以方便您后续在引力平台使用数据分析功能（ $city、 $province 、 $country 、 $browser 、 $browser_version 属性可以不上报，引力后端会自动采集）；
关于属性的更多信息，请您参考事件属性页面。

1. 环境要求

Golang 1.25.5 及以上版本。

2. 安装集成

自动集成

import    "github.com/GravityInfinite/go-sdk"

手动下载

直接下载：下载地址

3. 初始化配置

基础配置

const ServerUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=XXXX"


func generateBatchConsumer() (gedata.GEConsumer, error) {
    config := gedata.GEBatchConfig{
       ServerUrl: ServerUrl,
       AutoFlush: true,
       BatchSize: 100,
       Interval:  20,
       Compress:  true,
    }
    return gedata.NewBatchConsumerWithConfig(config)
}

func generateDebugConsumer() (gedata.GEConsumer, error) {
    return gedata.NewDebugConsumer(ServerUrl)
}

// e.g. init consumer, you can choose different consumer

//consumer, err := generateDebugConsumer() // GEDebugConsumer
consumer, err := generateBatchConsumer() // GEBatchConsumer 

if err != nil {
    // consumer init error
}


if err != nil {
    // consumer init error
}
ge := gedata.New(consumer)

核心功能

1. 事件追踪

如需上报自定义事件，您必须先在元事件中添加，否则会上报失败！

您可以调用 track 方法，记录用户自定义事件。

您需要先在元事件中添加自定义事件，然后调用 track 方法上报自定义事件。

// 设置事件属性
properties := map[string]interface{}{
    // 系统预置属性
    "$city": "xx",
    // 用户自定义属性, 字符串类型
    "prop_string": "abcdefg",
    // 用户自定义属性, 数值类型
    "prop_num": 56.56,
    // 用户自定义属性, bool 类型
    "prop_bool": true,
    // 用户自定义属性, time.Time 类型
    "prop_date": time.Now(),
}
err := ge.Track(clientId, eventName, properties)

事件的名称是字符串类型，为字符串类型。
Key 为该属性的名称，为字符串类型。
Value 为该属性的值，支持字符串、数字、布尔、时间、对象、对象组、数组

2. 用户属性管理

设置用户属性（覆盖）

对于一般的用户属性，您可以调用来UserSet进行设置，使用该接口上传的属性将会覆盖原有的属性值，如果之前不存在该用户属性，则会新建该用户属性。

properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
err := ge.UserSet(clientId, properties)

初始化用户属性（仅首次设置有效）

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

properties := map[string]interface{}{"prop_once": "xxx"}
err := ge.UserSetOnce(clientId, properties)

累加用户属性

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

properties := map[string]interface{}{"prop_incr": 123}
err := ge.UserIncrement(clientId, properties)

用户属性取最大值

对于数值型的用户属性，可以使用 UserMax用来比较数值大小，保存较大的，如果没有这个 key，则新增 key，value 取本次的值。

properties := map[string]interface{}{"prop_num": 100}
err := ge.UserMax(clientId, properties)

用户属性取最小值

对于数值型的用户属性，可以使用 UserMin用来比较数值大小，保存较小的，如果没有这个 key，则新增 key，value 取本次的值。

properties := map[string]interface{}{"prop_num": 1}
err := ge.UserMin(clientId, properties)

用户属性追加

对用户喜爱的电影、用户点评过的餐厅等属性，可以调用 UserAppend记录列表型属性。

properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err := ge.UserAppend(clientId, properties)

用户属性去重追加

调用 UserUniqAppend用来对 Array 类型的用户数据去重追加元素。

properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
err := ge.UserUniqAppend(clientId, properties)

重置用户属性

如果需要重置已设置的某个用户属性，可以调用 UserUnset进行重置。

properties := map[string]interface{}{"prop_unsete": "xxx"}
err := ge.UserUnset(clientId, properties)

清空用户属性

调用 UserDelete方法，将把当前用户属性清空，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

err := ge.UserDelete(clientId)

3. 数据管理

立即上报数据

ge.flush();

注意: 频繁调用 flush() 会影响性能，建议在重要操作后调用。

关闭 SDK

ge.close();

在应用关闭前调用，确保缓存数据不会丢失。

完整示例

package main

import (
    "fmt"

    "time"

    // "gedata/src/gedata"
    "github.com/GravityInfinite/go-sdk/src/gedata"
)

const ServerUrl = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___"

const clientId = "_test_client_id_0"
const eventName = "$AdClick"

var trackProperties = func() map[string]interface{} {
    type B struct {
        Trigger string
        Time    time.Time
    }
    type A struct {
        Name  string
        Time  time.Time
        Event []B
    }

    customData := A{
        eventName,
        time.Now(),
        []B{
            {Trigger: "Now We Support", Time: time.Now()},
            {Trigger: "User Custom Struct Data", Time: time.Now()},
        },
    }
    properties := map[string]interface{}{
        "channel":   "ge",
        "age":       1,
        "isSuccess": true,
        "birthday":  time.Now(),
        "object": map[string]interface{}{
            "key": "value",
        },
        "objectArr": []interface{}{
            map[string]interface{}{
                "key": "value",
            },
        },
        "arr":      []string{"test1", "test2", "test3"},
        "my_data":  customData,
        "time_now": time.Now(),
        "time_2":   "2022-12-12T22:22:22.333444555Z",
    }
    return properties
}()

func mainDebug() {

    // e.g. init consumer, you can choose different consumer

    consumer, err := generateDebugConsumer() // GEDebugConsumer
    //consumer, err := generateBatchConsumer() // GEBatchConsumer

    if err != nil {
        // consumer init error
        panic(err)
    }
    ge := gedata.New(consumer)

    defer func() {
        err = ge.Flush()
        if err != nil {
            fmt.Printf("GE flush error: %v", err.Error())
        }
        err = ge.Close()
        if err != nil {
            fmt.Printf("GE close error: %v\n", err.Error())
        }
    }()

    func() {
        for i := 0; i < 6; i++ {
            p := trackProperties
            p["idx"] = i
            err = ge.Track(clientId, eventName, p)
            if err != nil {
                fmt.Println(err)
            }
        }

    }()

    func() {
        properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
        _ = properties
        err = ge.UserSet(clientId, trackProperties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"user_name": ""}
        err = ge.UserUnset(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_set_once": "111"}
        err = ge.UserSetOnce(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"TotalRevenue": 100}
        err = ge.UserIncrement(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"TotalRevenue": 1}
        err = ge.UserNumMin(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"TotalRevenue": 1000}
        err = ge.UserNumMax(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_list_type": []string{"a", "a"}}
        err = ge.UserAppend(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
        err = ge.UserUniqAppend(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        err = ge.UserDelete(clientId)
        if err != nil {
            fmt.Println(err)
        }

    }()
}

func mainBatch() {
    // e.g. init consumer, you can choose different consumer

    //consumer, err := generateDebugConsumer() // GEDebugConsumer
    consumer, err := generateBatchConsumer() // GEBatchConsumer

    if err != nil {
        // consumer init error
        panic(err)
    }
    ge := gedata.New(consumer)

    defer func() {
        err = ge.Flush()
        if err != nil {
            fmt.Printf("GE flush error: %v", err.Error())
        }
        err = ge.Close()
        if err != nil {
            fmt.Printf("GE close error: %v\n", err.Error())
        }
    }()

    func() {
        for i := 0; i < 1000; i++ {
            p := trackProperties
            p["idx"] = i
            err = ge.Track(clientId, eventName, p)
            if err != nil {
                fmt.Println(err)
            }
        }

    }()

    func() {
        properties := map[string]interface{}{"user_name": "xxx", "count": 1, "arr": []int{11, 22}}
        err = ge.UserSet(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"user_name": ""}
        err = ge.UserUnset(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_set_once": "111"}
        err = ge.UserSetOnce(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"TotalRevenue": 100}
        err = ge.UserIncrement(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_list_type": []string{"a", "a"}}
        err = ge.UserAppend(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        properties := map[string]interface{}{"prop_list_type": []string{"a", "b", "c", "c"}}
        err = ge.UserUniqAppend(clientId, properties)
        if err != nil {
            fmt.Println(err)
        }

    }()

    func() {
        err = ge.UserDelete(clientId)
        if err != nil {
            fmt.Println(err)
        }

    }()

}

func main() {
    // enable console log
    gedata.SetLogLevel(gedata.GELogLevelDebug)
    func() {
        mainDebug()
        //mainBatch()
    }()
    fmt.Println("ok")
}

func generateBatchConsumer() (gedata.GEConsumer, error) {
    config := gedata.GEBatchConfig{
        ServerUrl: ServerUrl,
        AutoFlush: true,
        BatchSize: 100,
        Interval:  20,
        Compress:  true,
    }
    return gedata.NewBatchConsumerWithConfig(config)
}

func generateDebugConsumer() (gedata.GEConsumer, error) {
    return gedata.NewDebugConsumer(ServerUrl)
}

最佳实践

异常处理: 对所有SDK调用进行异常捕获
资源清理: 在应用关闭前调用 close()方法
属性命名: 使用有意义的属性名称，保持一致性
数据类型: 确保属性值类型符合预期，避免类型错误

故障排除

常见问题

初始化问题: 检查 ACCESS_TOKEN 和服务器地址是否正确
数据格式: 验证事件属性数据类型是否符合要求
性能问题: 避免频繁调用 flush() 方法

事件采集