跳到主要内容
Gravity Engine 引力引擎服务端集成
Gravity Engine 引力引擎

GO SDK

介绍 Gravity Engine GO SDK 的环境要求、安装初始化、事件追踪和用户属性管理,并提供参数说明与代码示例。

查看 Markdown

概述

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
}
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 比较数值大小,保存较大的值。

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

用户属性取最小值

对于数值型的用户属性,可以使用 UserMin 比较数值大小,保存较小的值。

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_unset": "xxx"}
err := ge.UserUnset(clientId, properties)

清空用户属性

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

err := ge.UserDelete(clientId)

3. 数据管理

立即上报数据

err := ge.Flush()
if err != nil {
    // handle error
}

注意

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

关闭 SDK

err := ge.Close()
if err != nil {
    // handle error
}

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

完整示例

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)
}

最佳实践

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

故障排除

常见问题

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

文档维护:Gravity Engine

文档修改日期:

本页内容