菜单

C++ SDK

概述

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

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

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

1. 环境要求

最低兼容3.7 版本

2. 安装集成

资源下载: 下载地址

自动集成

#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"

3. 初始化配置

基础配置

#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"

#include <thread>
#include <chrono>


using namespace GEData;

// enable debug
#ifdef _DEBUG
#ifndef DBG_NEW
#define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ )
#define new DBG_NEW
#endif
#endif  // _DEBUG

const static std::string SERVER_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=___XXX___";

std::unique_ptr<GEConsumer> getBatchConsumer() {
    // 批提交数据条数4，默认值20
    std::unique_ptr<GEConsumer> ptr(new GEBatchConsumer(SERVER_URL,4));
    return ptr;
}

std::unique_ptr<GEConsumer> getDebugConsumer() {
    std::unique_ptr<GEConsumer> ptr(new GEDebugConsumer(SERVER_URL));
    return ptr;
}

核心功能

1. 事件追踪

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

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

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

std::string clientId = "_test_client_id_0";
std::string eventName = "$AdClick";

for (int i = 0; i <= 1; ++i) {
    GEPropertiesNode properties;

    properties.SetNumber("idx", i);
    properties.SetString("name1", "2-新消息");
    properties.SetString("name2", "logBugs");
    properties.SetString("name3", "name3");
    properties.SetNumber("test_number_int", 3);
    properties.SetNumber("test_number_double", 3.14);
    properties.SetBool("test_bool", true);
    properties.SetString("test_stl_string1", "string1");

    timeb t1 = {};
    ftime(&t1);
    properties.SetDateTime("time2", t1.time, t1.millitm);

    std::vector<std::string> list;
    list.emplace_back("item11");
    list.emplace_back("item21");
    properties.SetList("test_list1", list);

    ge.track(clientId, eventName, properties);
}

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

2. 用户属性管理

设置用户属性（覆盖）

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

try:
    user_properties = {"user_name": 'XXX', 'count': 1, 'arr': ['111', '222']}
    ge.user_set(client_id="client_id", properties=user_properties)
except Exception as e:
    raise GEIllegalDataException(e)

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

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

GEPropertiesNode user_set_once_properties;
user_set_once_properties.SetString("prop_set_once", "ABC");
ge.user_set_once(clientId, user_set_once_properties);

累加用户属性

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

GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue",100);
ge.user_increment(clientId, user_change_num_properties);

用户属性取最大值

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

GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue", 1000);
ge.user_max(clientId, user_change_num_properties);

用户属性取最小值

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

GEPropertiesNode user_change_num_properties;
user_change_num_properties.SetNumber("TotalRevenue",1);
ge.user_min(clientId, user_change_num_properties);

用户属性追加

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

GEPropertiesNode userAppend_properties;
std::vector<std::string> userAppendListValue;
userAppendListValue.emplace_back("11");
userAppendListValue.emplace_back("33");
userAppend_properties.SetList("prop_list_type", userAppendListValue);
ge.user_append(clientId, userAppend_properties);

用户属性去重追加

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

GEPropertiesNode userUniqAppend_properties;
std::vector<std::string> userUniqAppendListValue;
userUniqAppendListValue.emplace_back("55");
userUniqAppendListValue.emplace_back("22");
userUniqAppendListValue.emplace_back("33");
userUniqAppendListValue.emplace_back("66");
userUniqAppendListValue.emplace_back("55");
userUniqAppend_properties.SetList("prop_list_type", userUniqAppendListValue);
ge.user_uniq_append(clientId, userUniqAppend_properties);

重置用户属性

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

GEPropertiesNode user_unset__properties;
user_unset__properties.SetNumber("TotalRevenue", 123);
ge.user_unset(clientId, user_unset__properties);

清空用户属性

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

ge.user_del(clientId);

3. 数据管理

立即上报数据

ge.flush()

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

关闭 SDK

ge.close()

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

完整示例

#include "../include/GEAnalytics.h"
#include "../include/GEDebugConsumer.h"
#include "../include/GEBatchConsumer.h"

#include <thread>
#include <chrono>


using namespace GEData;

// enable debug
#ifdef _DEBUG
#ifndef DBG_NEW
#define DBG_NEW new ( _NORMAL_BLOCK , __FILE__ , __LINE__ )
#define new DBG_NEW
#endif
#endif  // _DEBUG

const static std::string SERVER_URL = "https://backend.gravity-engine.com/event_center/api/v1/event/collect/?access_token=x5emsWAxqnlwqpDH1j4bbicR8igmhruT";

std::unique_ptr<GEConsumer> getBatchConsumer() {
    // 批提交数据条数4，默认值20
    std::unique_ptr<GEConsumer> ptr(new GEBatchConsumer(SERVER_URL,4));
    return ptr;
}

std::unique_ptr<GEConsumer> getDebugConsumer() {
    std::unique_ptr<GEConsumer> ptr(new GEDebugConsumer(SERVER_URL));
    return ptr;
}



int main(int argc, char *argv[]) {

    GELog::enable = true;

   std::unique_ptr<GEConsumer> consumer = getDebugConsumer();

    // std::unique_ptr<GEConsumer> consumer = getBatchConsumer();

    GEAnalytics ge(*consumer);


    std::string clientId = "_test_client_id_0";
    std::string eventName = "$AdClick";

    for (int i = 0; i <= 100; ++i) {
        GEPropertiesNode properties;

        properties.SetNumber("idx", i);
        properties.SetString("name1", "2-新消息");
        properties.SetString("name2", "logBugs");
        properties.SetString("name3", "name3");
        properties.SetNumber("test_number_int", 3);
        properties.SetNumber("test_number_double", 3.14);
        properties.SetBool("test_bool", true);
        properties.SetString("test_stl_string1", "string1");

        timeb t1 = {};
        ftime(&t1);
        properties.SetDateTime("time2", t1.time, t1.millitm);

        std::vector<std::string> list;
        list.emplace_back("item11");
        list.emplace_back("item21");
        properties.SetList("test_list1", list);

        ge.track(clientId, eventName, properties);
    }



    GEPropertiesNode user_set_properties;
    user_set_properties.SetString("user_name", "test1");
    ge.user_set(clientId, user_set_properties);

    GEPropertiesNode user_set_once_properties;
    user_set_once_properties.SetString("prop_set_once", "ABC");
    ge.user_set_once(clientId, user_set_once_properties);

    GEPropertiesNode user_change_num_properties;
    user_change_num_properties.SetNumber("TotalRevenue",100);
    ge.user_increment(clientId, user_change_num_properties);

    user_change_num_properties.Clear();
    user_change_num_properties.SetNumber("TotalRevenue", 1000);
    ge.user_max(clientId, user_change_num_properties);


    user_change_num_properties.Clear();
    user_change_num_properties.SetNumber("TotalRevenue",1);
    ge.user_min(clientId, user_change_num_properties);


    GEPropertiesNode userAppend_properties;
    std::vector<std::string> userAppendListValue;
    userAppendListValue.emplace_back("11");
    userAppendListValue.emplace_back("33");
    userAppend_properties.SetList("prop_list_type", userAppendListValue);
    ge.user_append(clientId, userAppend_properties);

    GEPropertiesNode userUniqAppend_properties;
    std::vector<std::string> userUniqAppendListValue;
    userUniqAppendListValue.emplace_back("55");
    userUniqAppendListValue.emplace_back("22");
    userUniqAppendListValue.emplace_back("33");
    userUniqAppendListValue.emplace_back("66");
    userUniqAppendListValue.emplace_back("55");
    userUniqAppend_properties.SetList("prop_list_type", userUniqAppendListValue);
    ge.user_uniq_append(clientId, userUniqAppend_properties);

    GEPropertiesNode user_unset__properties;
    user_unset__properties.SetNumber("TotalRevenue", 123);
    ge.user_unset(clientId, user_unset__properties);

    ge.user_del(clientId);

    ge.flush();
    ge.close();

    return 0;
}

最佳实践

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

故障排除

常见问题

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

上一个

PHP SDK

下一个

小游戏Token接入

最近修改: 2026-02-26Powered by