C++ SDK 使用说明

最后更新于:2019-04-24 14:56:15

在使用前,请先阅读数据模型的介绍。

1. 概述

本文档所介绍的 C++ SDK 是用于记录客户端埋点的(而不是服务端),例如在 MFC 程序中集成,以收集用户在程序界面上的操作。若需要服务端埋点,请使用 神策分析 C SDK

本 SDK 区别于其他 SDK 在于将数据通过网络发送到服务端需要在代码适当的位置显式调用 Flush() 函数:

  1. 将数据发送到服务端需要有可用的网络连接;
  2. 在适当的位置调用,如后台线程,避免阻塞界面操作等。

进程退出时,若内存中仍有未 Flush 发送到服务端的数据,则会将数据保存到指定的暂存文件里,下次 Flush 时会从文件加载一起发送。可以通过参数调整最多暂存的数据条数,若未发送的数据条数超过该值,则从最早的数据开始淘汰。

  • 对暂存文件的读写未使用文件锁,请避免多进程操作同一个文件。

2. 集成神策分析 SDK

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

./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,具体方法可以搜索。

2.1 Windows 下 SDK 依赖

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

2.1.1 使用我们编译的 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 也可以引入并使用这个预编译的库。

2.1.2 自行编译 curl

  1. 下载 curl 源码:https://curl.haxx.se/download/curl-7.61.1.zip 并解压;
  2. 开始菜单中打开 Visual Studio 目录中的 VS2017的开发人员命令提示符,并切换到 curl 解压目录下的 winbuild 目录下;
  3. 执行命令开始编译:

    nmake /f Makefile.vc mode=dll
    

    如需要静态编译:

    nmake /f Makefile.vc mode=static ENABLE_IDN=no
    
  4. 编译输出在 curl 目录 builds 下。

如果需要静态链接 curl,需要在项目配置中:

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

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

2.1.3 自行编译 zlib

  1. 下载 zlib 源码:https://zlib.net/zlib-1.2.11.tar.gz
  2. 开始菜单中打开 Visual Studio 目录中的 VS2017的开发人员命令提示符,并切换到 zlib 解压目录下;
  3. 执行命令开始编译:

    nmake -f win32/Makefile.msc
    
  4. 编译输出在 zlib 目录下。

3. 初始化神策分析 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。更多关于标识用户的介绍请见如何准确的标识用户

4. 追踪事件

首次接入神策分析时,建议先追踪 3~5 个关键的事件,只需要几行代码,便能体验神策分析的分析功能。例如:

  • 图片社交产品,可以追踪用户浏览图片和评论事件
  • 电商产品,可以追踪用户注册、浏览商品和下订单等事件

用户通过

// 跟踪一个用户的行为
sensors_analytics::Sdk::Track(event_name);
sensors_analytics::Sdk::Track(event_name, event_properties);

接口记录事件。以 App 产品为例,可以这样追踪一次启动行为:

sensors_analytics::PropertiesNode event_properties;
event_properties.SetString("computer_name", "MyComputer");
sensors_analytics::Sdk::Track("OpenApp", event_properties);

4.1 事件属性

如前文中的样例,开发者追踪的事件可以自定义事件的属性,例如购买商品事件中,将商品 ID、商品分类等信息作为事件属性。在后续的分析工作中,事件属性可以作为统计过滤条件使用,也可以作为维度进行多维分析。对于事件属性,神策分析有一些约束:

  • 事件属性是一个 sensors_analytics::PropertiesNode 对象;
  • 通过 PropertiesNode 的方法设置属性,属性名称必需是字符串类型,以大小写字母开头,由字母和数字组成,长度不超过100个字符;
  • PropertiesNode 属性值支持 StringNumberBoolListDateTime,对于神策分析中事件属性的更多约束,请参考 数据格式

开发者可以通过以下接口,向 PropertiesNode 对象加入属性值,如加入 Bool 类型的属性:

sensors_analytics::PropertiesNode event_properties;
event_properties.SetBool("use_ticket", true);

其中属性名称必须为大小写字母开头、长度不超过 100 的由字母和数字组成的字符串。加入 Number 类型的属性:

event_properties.SetNumber("price", 100.0);

加入 DateTime 类型的属性,其中第一个参数为 time_t 类型,如系统函数 time(NULL) 的返回值,第二个参数为毫秒部分。或者直接用一个字符串作为 DateTime 类型属性的值:

event_properties.SetDateTime("view_from_time", time(NULL), 0);
event_properties.SetDateTime("view_to_time", "2018-09-12 18:02:15.234");

加入 String 类型的属性,字符串必须为 UTF-8 编码,字符串长度为实际的 UTF-8 长度,如一个汉字占 3 个字节:

event_properties.SetString("view_page_title", "title1");

std::string page_name = "page-1";
event_properties.SetString("view_page_name", page_name);

向 List 类型的属性中添加 String 对象:

std::vector<string> item_list;
item_list.push_back("Book1");
item_list.push_back("Movie2");
event_properties.SetList("view_items", item_list);

具体使用方式,可以参考上一节中的样例。

5. 追踪登录与 ID 关联

Init 时使用了随机生成的“设备 ID”,当获取到“登录 ID”后,可调用 SDK 的 Login 方法将“设备 ID”与“登录 ID”关联:

sensors_analytics::Sdk::Login("123456");

更详细的说明请参考 如何准确的标识用户,并在必要时联系我们的技术支持人员。

6. 设置用户属性

为了更准确地提供针对人群的分析服务,神策分析 SDK 可以设置用户属性,如年龄、性别等。用户可以在留存分析、分布分析等功能中,使用用户属性作为过滤条件或以用户属性作为维度进行多维分析。使用

sensors_analytics::Sdk::ProfileSet(const PropertiesNode& properties);

设置用户属性,例如在电商应用中,用户注册时,填充了一些个人信息,可以用 Profile 接口记录下来:

sensors_analytics::PropertiesNode profile_properties;
profile_properties.SetString("vip_level", "3");
sensors_analytics::Sdk::ProfileSet(profile_properties);

// 设置单个用户属性也可以通过:
sensors_analytics::Sdk::ProfileSetNumber("Age", 26);

用户属性中,属性名称与属性值的约束条件与事件属性相同,详细说明请参考 数据格式

6.1 记录初次设定的属性

对于只在首次设置时有效的属性,我们可以使用

sensors_analytics::Sdk::ProfileSetOnce(const PropertiesNode& properties);

接口记录这些属性。与 ProfileSet 接口不同的是,如果被设置的用户属性已存在,则这条记录会被忽略而不会覆盖已有数据,如果属性不存在则会自动创建。因此,ProfileSetOnce 比较适用于为用户设置首次相关属性。例如:

sensors_analytics::Sdk::ProfileSetOnceString("first_visit_page", "Page567");

7. 其他

7.1 使用 HTTPS 数据接收地址

使用 HTTPS 数据接收地址需要 curl 配置了 OpenSSL(建议)或 WinSSL(默认),我们提供的编译好的 curl 使用了 OpenSSL。

另外在某些操作系统里,curl 无法正确获取 ca-bundle,有两种方法处理:

  1. 不添加 ca-bundle,不校验服务端 SSL 证书(会降低传输安全性,建议仅测试时使用)。具体做法是在 sensors_analytics_sdk.cpp 文件中搜索 CURLOPT_SSL_VERIFYPEER,取消相关两行代码的注释;
  2. 附带 ca-bundle(下载地址)。具体做法是在 sensors_analytics_sdk.cpp 文件中搜索 CURLOPT_CAINFO,取消该行注释,并指定证书文件的路径。