集成文档（C++）

集成神策分析 SDK

SDK 源文件可从 https://github.com/sensorsdata/sa-sdk-cpp 获取。使用时可以将代码直接集成到目标项目中，或先编译为库再引入，SDK 源代码包括：

./include/sensors_analytics_sdk.h
./include/sensors_network.h
./include/sensors_utils.h
./src/sensors_analytics_sdk.cpp
./src/sensors_network.cpp
./src/sensors_utils.cpp

./include/sensors_analytics_sdk.h
./src/sensors_analytics_sdk.cpp

./include/sensors_analytics_sdk.h
./include/sensors_network.h
./include/sensors_utils.h
./src/sensors_analytics_sdk.cpp
./src/sensors_network.cpp
./src/sensors_utils.cpp

./include/sensors_analytics_sdk.h
./src/sensors_analytics_sdk.cpp

SDK 依赖的第三方库包括：

1. curl：用于网络请求；
2. zlib：用于 gzip 压缩。

其他说明：

• GitHub 上的 vs2005 分支代码支持在 Visual Studio 2005 版本的 C++ 下编译使用。
• 若直接引入源代码文件并使用 Visual Studio 编译报错，请看最开始的报错是否是“warning C4819： 该文件包含不能在当前代码页（936）中表示的字符。请将该文件保存为 Unicode 格式以防止数据丢失”，可以将引入的几个代码文件“文件 > 高级保存选项 > 编码 > Unicode - 代码页 1200”然后保存再尝试编译。VS2017 及以上可以搜索 “Visual Studio 2017 隐藏高级保存选项” 找到该功能。
• 字符串类型的属性值（主要是使用中文值时）需要是合法的 UTF-8 编码，否则会在 stderr 报错无法导入字段，这时请检查是否使用了 GBK 编码（例如这个字符串所在源代码文件是用 GBK 编码保存的）。将 GBK 编码的 string 转成 UTF-8 的方法，Windows 下可以用 MultiByteToWideChar、WideCharToMultiByte；Linux 下可以用 iconv，具体方法可以搜索。

 Windows 下 SDK 依赖

您可以直接尝试使用我们编译好的依赖文件，或自行编译。

使用我们编译的 curl 和 zlib

我们在 Visual Studio 2005 上编译了适用 Windows XP 的 curl 和 zlib。使用方法如下：

1. 下载 curl 源代码，在项目名上右键 > 属性 > C/C++ > 常规 > “附加包含目录” 添加 curl 源代码目录下的 include 目录；
2. 下载 zlib 源代码，在项目名上右键 > 属性 > C/C++ > 常规 > “附加包含目录” 添加 zlib 源代码目录；
3. 下载编译好的 curl 和 zlib 库文件，在项目的“资源文件”右键 > 添加 > 现有项，选择 libcurl.dll、libcurl.lib、zlib.lib；

更高版本的 Visual Studio 也可以引入并使用这个预编译的库。

自行编译 curl

1. 下载 curl 源码：https://curl.se/download.html；
2. 开始菜单中打开 Visual Studio 目录中的 VS2017 的开发人员命令提示符，并切换到 curl 解压目录下的 winbuild 目录下；
3. 执行命令开始编译，见下面的代码片：
4. 编译输出在 curl 目录 builds 下。

nmake /f Makefile.vc mode=dll

如需要静态编译：

nmake /f Makefile.vc mode=static ENABLE_IDN=no

如果需要静态链接 curl，需要在项目配置中：

1. 链接器 > 常规 > 链接库依赖，添加 libcurl_a.lib;Ws2_32.lib;Wldap32.lib;winmm.lib;Crypt32.lib
2. 在C/C++ > 预处理器 > 预处理器定义中，加入 CURL_STATICLIB

另外，若希望上报数据使用 HTTPS 做传输加密，建议编译 curl 时配置使用 OpenSSL 以获取更好的兼容性，或使用我们编译好的 curl。

自行编译 zlib

1. 从 zlib 官网下载 zlib 源码
2. 开始菜单中打开 Visual Studio 目录中的 「VS2017 的开发人员命令提示符」，并切换到 zlib 解压目录下；
3. 执行命令开始编译：
4. 编译输出在 zlib 目录下。

nmake -f win32/Makefile.msc

 初始化神策分析 SDK

在程序中使用

// 初始化 SDK
// data_file_path: 暂存文件路径，用于将未发送的数据临时保存在磁盘
// server_url: 数据接收地址
// distinct_id: 标识一个用户的 ID
// is_login_id: distinct_id 参数传值是否是一个“登录 ID”
// max_staging_record_count: 在发送队列中最多保存的数据条数，若当前未发送数据条数达到该值，
//                           新埋点记录将淘汰最早的一个记录
sensors_analytics::Sdk::Init(staging_file_path,
                             server_url,
                             distinct_id,
                             is_login_id,
                             max_staging_record_size);

distinct_id 是标识用户的 ID，若初始化 SDK 时无可用 ID，可以随机生成一个 UUID 作为 distinct_id，并且 is_login_id 传值为 false，并将这个 ID 保存起来，下次初始化 SDK 时传入相同的值；若有可用的登录 ID，可以传入登录 ID的值，并且 is_login_id 传值为 true。