菜单

快速集成

本文档为C++接入引力引擎的技术接入方案。建议您先阅读接入前准备以了解接入必备的基础概念。

1. SDK 基础配置

下载最新的SDK 文件，并导入到您的项目中

将整个 GravityEngineSDK/ 目录复制到你的项目中，然后用 CMake 引入。

1.1 CMake 接入（推荐）

SDK 通过 target_include_directories PUBLIC 自动将头文件路径传递给依赖它的目标，无需手动配置 include 路径。

场景 A：SDK 在项目子目录内

your_project/
├── GravityEngineSDK/   ← 复制到这里
├── src/
└── CMakeLists.txt

add_subdirectory(GravityEngineSDK)

add_executable(your_app src/main.cpp)
target_link_libraries(your_app gedata)

场景 B：SDK 与项目平级（如本 demo 的结构）

workspace/
├── GravityEngineSDK/
└── your_project/
    ├── main.cpp
    └── CMakeLists.txt

set(SDK_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../GravityEngineSDK") 
add_subdirectory(${SDK_DIR} ${CMAKE_CURRENT_BINARY_DIR}/gedata_build) 

add_executable(your_app main.cpp) 
target_link_libraries(your_app gedata)

两种场景的源码写法完全相同：

#include "GEAnalytics.h"   // 无需写路径，CMake 自动处理

手动编译（macOS / Linux）

clang++ -std=c++11 \
  -I GravityEngineSDK/include \
  -I GravityEngineSDK/src \
  GravityEngineSDK/src/*.cpp \
  your_app.cpp \
  -lcurl -lpthread \
  -o your_app

# macOS 额外添加
# -framework IOKit -framework CoreFoundation

Windows（MSVC）

包含目录：  GravityEngineSDK\include
           GravityEngineSDK\src
           GravityEngineSDK\thirdParty\curl\include
附加库目录：GravityEngineSDK\thirdParty\curl\lib
附加依赖项：libcurl.lib  Advapi32.lib

头文件引入

#include "GEAnalytics.h"

2.初始化

在用户可以获取到用户唯一性信息时调用 initialize 方法，后续其他方法均需在本方法回调成功之后才可正常使用。

首次调用后，需要在 initialize的成功之后才能继续调用其他事件上报的方法

方法示例

#include "GEAnalytics.h"
#include <thread>
#include <chrono>

using namespace GEData;

int main() {
    // 1. 配置初始化参数
    GEPropertiesNode config;
    config.SetString("access_token", "YOUR_ACCESS_TOKEN");  // 必填
    config.SetString("client_id",    "unique_device_id");   // 必填
    config.SetBool  ("is_china",     true);   // true=国内，false=海外
    config.SetBool  ("enable_log",   true);   // 开启调试日志
    config.SetString("channel",      "windows_store");  //渠道名
    config.SetString("name",      "username"); //用户名
    config.SetNumber("version",      2); //应用版本号


    // 2. 初始化 SDK（异步，回调在后台线程触发）
    GEAnalytics::initialize(config, [](bool ok, const std::string& msg) {
        if (!ok) {
            // 失败原因见 msg，常见：access_token 无效、网络不通
            return;
        }

        // 3. 初始化成功后即可上报
        GEPropertiesNode props;
        props.SetString("scene", "launch");
        GEAnalytics::track("$AppStart", props);

        GEAnalytics::flush();
    });

    // 主循环占位（实际项目替换为你的事件循环）
    std::this_thread::sleep_for(std::chrono::seconds(5));

    GEAnalytics::close();  // 退出前必须调用
    return 0;
}

参数说明

参数名称	参数含义	参数类型	是否必传
access_token	应用凭证。您可以在设置-应用管理页面点击查看参数按钮获取当前应用的 AccessToken	string	是
client_id	当前用户在引力系统中的唯一标识	string	是
is_china	是否使用国内域名	bool	是
enable_log	是否打开日志	bool	否
name	用户名或用户唯一ID（可理解为业务中的昵称）	string	否
version	用户初始化的程序发布更新的版本号	number	否
channel	当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base_channel）	string	否

3.事件上报

3.1事件上报

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

建议您先在元事件中添加事件，然后在页面中指定位置埋点调用 track 方法上报自定义事件。

GEPropertiesNode props;
props.SetString("item_id", "sku_001");
props.SetNumber("price",   99.9);
props.SetBool  ("is_gift", false);

GEAnalytics::track("Purchase", props);

事件名称是 string 类型，只能以字母开头，可包含数字，字母和下划线 “_”，长度最大为 50 个字符。
事件属性是 Record<string, object> 类型，其中每个元素代表一个属性；
事件属性 Key 为属性名称，为 string 类型，规定只能以字母开头，包含数字，字母和下划线 “_”，长度最大为 50 个字符；
属性 Value 支持string、number、boolean、Date、Array<string>；

当您调用track 时，SDK 会取系统当前时间作为事件发生的时刻，如果您需要指定事件时间，可以传入 Date 类型的参数来设置事件触发时间。

尽管事件可以设置触发时间，但是接收端会做如下的限制：只接收相对服务器时间在前 10 天至后 1 小时的数据，超过时限的数据将会被视为异常数据，整条数据无法入库!

3.2数据上报控制

SDK 内部缓冲事件，累积满 20 条后自动触发网络请求。

GEAnalytics::flush();  // 立即上报全部缓冲数据
GEAnalytics::close();  // flush 后释放资源（程序退出前必须调用）

注意： 程序退出前未调用 close()，缓冲中不足 20 条的数据不会发送。

4.接入验证

正式上线之前，请完成本节的校验，否则可能会导致买量上报异常！

4.1 关键事件验证

在引力后台事件流界面开启加载实时数据，并在产品中触发以下几个事件。事件流使用说明：‬⁠⁠‬‌‌‍‍⁠⁠⁠⁠‍⁠‬‍⁠‍‌⁠⁠⁠‬‬事件流 - 飞书云文档

事件名	事件英文名	触发时机	采集方式	默认映射到媒体事件	备注
付费	`$PayEvent`	用户付费之后	调用SDK的上报用户付费事件方法采集	付费	接入了付费事件上报事件的产品均需要校验

触发操作后，请在事件流界面中筛选测试用户的 Client ID，观察对应事件是否出现在实时入库页面。若事件数据正常显示，则说明接入成功；如出现于错误数据页面请根据页面错误提示进行排查；如未显示对应数据，请及时联系引力运营支持团队获取协助。

4.2 避免重复上报

如果您之前单独接了媒体的回传(SDK 或者 API)，则上线之前需要去掉，否则可能会导致重复上报数据！

至此验证无误之后，您可以正常上线了。

上一个

C++

下一个

用户属性上报

最近修改: 2026-06-03Powered by