# C++快速集成

> 来源：https://help.gravity-engine.com/docs/client-sdk/cpp/quickstart
> 介绍 Gravity Engine C++ SDK 的安装、初始化、用户注册与事件上报流程，并提供参数说明和调用示例。



本文档为 **C++** 接入 [引力引擎](https://gravity-engine.com/) 的技术接入方案，建议您先阅读 [接入前准备](/docs/getting-started/overview) 以了解接入必备的基础概念。

## 1. SDK 基础配置 [#1-sdk-基础配置]

下载最新的 [SDK](/docs/client-sdk/sdk-overview) 文件，并导入到您的项目中。

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

### 1.1 CMake 接入（推荐） [#11-cmake-接入推荐]

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

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

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

```cmake
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
```

```cmake
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)
```

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

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

### 1.2 手动编译（macOS / Linux） [#12-手动编译macos--linux]

```bash
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
```

### 1.3 Windows（MSVC） [#13-windowsmsvc]

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

### 1.4 头文件引入 [#14-头文件引入]

```cpp
#include "GEAnalytics.h"
```

## 2. 初始化 [#2-初始化]

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

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

### 2.1 方法示例 [#21-方法示例]

```cpp
#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;
}
```

### 2.2 参数说明 [#22-参数说明]

| **参数名称**      | **参数含义**                                                                                                 | **参数类型** | **是否必传** |
| ------------- | -------------------------------------------------------------------------------------------------------- | -------- | -------- |
| access\_token | 应用凭证。您可以在[设置-应用管理](https://web.gravity-engine.com/#/manage/appmanage)页面点击 **查看参数** 按钮获取当前应用的 AccessToken | string   | 是        |
| client\_id    | 当前用户在引力系统中的唯一标识                                                                                          | string   | 是        |
| is\_china     | 是否使用国内域名                                                                                                 | bool     | 是        |
| enable\_log   | 是否打开日志                                                                                                   | bool     | 否        |
| name          | 用户名或用户唯一ID（可理解为业务中的昵称）                                                                                   | string   | 否        |
| version       | 用户初始化的程序发布更新的版本号                                                                                         | number   | 否        |
| channel       | 当前用户来源渠道，对应用户细查中的：客户端渠道（默认值：base\_channel）                                                               | string   | 否        |

## 3. 事件上报 [#3-事件上报]

### 3.1 事件上报 [#31-事件上报]

> **如需上报事件，您必须先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加，否则会上报失败！**

建议您先在[元事件](https://web.gravity-engine.com/#/manage/metadata/metaEvent)中添加事件，然后在页面中指定位置埋点调用 `track` 方法上报自定义事件。

```cpp
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 数据上报控制 [#32-数据上报控制]

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

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

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

## 4. 接入验证 [#4-接入验证]

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

### 4.1 关键事件验证 [#41-关键事件验证]

在引力后台[事件流](https://web.gravity-engine.com/#/manage/metadata/eventFlow) 界面开启**加载实时数据**，并在产品中触发以下几个事件。事件流使用说明：[事件流 - 飞书云文档](https://gravityengine.feishu.cn/wiki/ZFmYwiDxfiZe2lkt3occ6yBonpf)

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

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

### 4.2 避免重复上报 [#42-避免重复上报]

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

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