menu
Is this helpful?

# C++

提示

在接入前, 请先阅读接入前准备

您可以在 GitHub (opens new window) 获取C++ SDK 源码。

C++ SDK 支持在Mac、Windows平台运行,支持C++ 11以上版本,大小约为 144KB

最新版本: 1.4.1

更新时间: 2024-01-04

资源下载:SDK源码 (opens new window)

# 一、集成 SDK

# 1.1 下载SDK

下载SDK源码 (opens new window),解压后进入cpp-client/cpp文件夹。

include 为 SDK 的头文件、src 为 SDK 源代码文件、thirdparty 为依赖的三方库。

# 1.2 添加依赖

C++ SDK 依赖 sqlite、curl、zlib 、openssl库,由于平台特性的差异,库的格式也有所不同。可使用数数编译好的库,也可以自行编译库。

# 1.2.1 使用数数编译的库

库是在 windows 平台的编译器生成的库,将 thirdparty 文件夹中编译好的库配置到项目中。(.dll 为动态库,.lib 为静态库)

# 1.2.2 自行编

这里以window平台为例:

下载curl库,https://github.com/curl/curl/releases/tag/curl-7_61_1,解压后,切换至winbuild 目录,并编译,编译命令如下, 编译结果在 curl 目录 builds 下。

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

下载zlib库,https://github.com/madler/zlib/releases/tag/v1.2.11,解压后,执行编译命令,编译结果在 zlib 目录下。

nmake -f win32/Makefile.msc

下载sqlite库,https://www.sqlite.org/download.html,选择指定平台的库。

WARNING

除了命令行的方式,也可以使用 IDE(集成开发环境) ,如 Visual Studio 、Clion 等来生成对应平台的库。

下载openssl库,https://github.com/openssl/openssl,自行编译指定平台的库。

# 1.3 集成SDK

# 1.3.1 使用 CMake 集成

使用 CMake 来集成 C++ SDK,将cpp文件夹拷贝到项目中,在CMakeLists.txt文件中分别为Windows 和 Mac 添加如下配置:

设置C++ 的版本:

set(CMAKE_CXX_STANDARD 11)

引入头文件:

include_directories(cpp/include)

添加 Windows 平台配置:

if(WIN32)
    if(CMAKE_SIZEOF_VOID_P EQUAL 8) # x64平台
        include_directories(cpp/thirdparty/x64/curl/include cpp/thirdparty/x64/zlib/include cpp/thirdparty/x64/sqlite/include cpp/thirdparty/x64/openssl/include)
        link_directories(cpp/thirdparty/x64/curl/lib cpp/thirdparty/x64/zlib/lib cpp/thirdparty/x64/sqlite/lib cpp/thirdparty/x64/openssl/lib)
    else() # Win32平台
        include_directories(cpp/thirdparty/x86/curl/include cpp/thirdparty/x86/zlib/include cpp/thirdparty/x86/sqlite/include cpp/thirdparty/x86/openssl/include)
        link_directories(cpp/thirdparty/x86/curl/lib cpp/thirdparty/x86/zlib/lib cpp/thirdparty/x86/sqlite/lib cpp/thirdparty/x86/openssl/lib)
    endif()
    add_library(thinkingdata SHARED cpp/src/ta_analytics_sdk.cpp cpp/src/ta_cpp_helper.cpp cpp/src/ta_cpp_network.cpp cpp/src/ta_cpp_utils.cpp cpp/src/ta_sqlite.cpp cpp/src/ta_timer.cpp cpp/src/ta_event_task.cpp cpp/src/ta_cpp_send.cpp cpp/src/ta_json_object.cpp cpp/src/ta_cJSON.c cpp/src/ta_encrypt.cpp cpp/src/ta_calibrated_time.cpp cpp/src/ta_flush_task.cpp)
    target_link_libraries(thinkingdata libcurl sqlite3 zlibwapi libssl libcrypto)
endif()

添加 Mac 平台配置:

if (CMAKE_HOST_APPLE)
    find_library(COCOA Cocoa)
    find_library(IOKIT IOKit)
    find_package(OpenSSL REQUIRED)
    include_directories(${OPENSSL_INCLUDE_DIR})
    link_directories(${OPENSSL_LIBRARIES})
    add_library(thinkingdata SHARED cpp/src/ta_analytics_sdk.cpp cpp/src/ta_cpp_helper.cpp cpp/src/ta_cpp_network.cpp cpp/src/ta_cpp_utils.cpp cpp/src/ta_sqlite.cpp cpp/src/ta_timer.cpp cpp/src/ta_event_task.cpp cpp/src/ta_cpp_send.cpp cpp/src/ta_json_object.cpp cpp/src/ta_cJSON.c cpp/src/ta_mac_tool.mm cpp/src/ta_encrypt.cpp cpp/src/ta_calibrated_time.cpp cpp/src/ta_flush_task.cpp)
    target_link_libraries(thinkingdata curl z sqlite3 ${OPENSSL_LIBRARIES} ${COCOA} ${IOKIT})
endif()

# 1.3.2 自行编译

可使用 IDE(集成开发环境)自行编译数数的库

  1. 下载好SDK 代码,cd到cmakelist文件目录下
  2. 执行以下命令
//windows平台 利用visual studio来编译
//x86
cmake -S . -B build -G "Visual Studio 17 2022" -A Win32
 //x64
cmake -S . -B build -G "Visual Studio 17 2022" -A x64
//Mac平台
// arm64平台 m1
arch -arm64 cmake -B build
arch -arm64 cmake --build build

//x86_64平台  intel
arch -x86_64 cmake -B build
arch -x86_64 cmake --build build

# 1.3.3 使用源码集成

在完成步骤1.2的三方依赖配置之后,将 include 和 src 文件夹添加至项目中。

# 1.3.4 使用数数编译好的库

SDK下载 (opens new window)

下载解压好,可以找到x64和x86平台相应的dll文件,可直接使用。

# 二、 初始化SDK

#include "ta_analytics_sdk.h"
#include "ta_json_object.h"

using namespace thinkingdata;

ThinkingAnalyticsAPI::Init(SERVER_URL, APPID);

参数说明:

  • APPID: 您的项目的 APPID,可通过在 TA 后台项目管理页面获取
  • SERVER_URL: 数据上传的 URL
    • 如果您对接的是云服务,填入: https://global-receiver-ta.thinkingdata.cn
    • 如果您使用私有化部署版本,请为数据采集地址绑定域名,并配置 HTTPS 证书:https://数据采集地址绑定域名

# 三、常用功能

在使用常用功能之前,建议你先了解用户识别规则;SDK默认会生成随机数作为访客ID,并持久化存储访客ID在本地;用户未登录之前,会以访客ID作为身份识别ID。注意:访客 ID 在用户重新安装 App 以及更换设备时将会变更。

# 3.1 设置账号ID

在用户进行登录时,可调用 Login 来设置用户的账号 ID, TA 平台将会以账号 ID 作为身份识别 ID,并且设置的账号 ID 将会在调用 Logout 之前一直保留。多次调用 Login 将覆盖先前的账号 ID 。

// 用户的登录唯一标识,此数据对应上报数据里的#account_id,此时#account_id的值为TA
ThinkingAnalyticsAPI::Login("TA");

Login 可以多次调用,每次调用会判断传入的账号 ID 与先前保存的 ID 是否一致,一致则忽略调用,不一致则会覆盖先前的 ID。

该方法不会上传登录事件

# 3.2 发送事件

您可以调用 track 来上传事件,建议您根据先前梳理的埋点文档来设置事件的属性以及发送信息的条件,此处以用户购买某商品作为范例:

TDJSONObject event_properties;
event_properties.SetString("name1", "name1");//字符串
event_properties.SetNumber("test_number_int", 3);//数字
event_properties.SetBool("test_bool", true);//bool
event_properties.SetDateTime("test_time1", time(NULL), 0);//时间
std::vector<std::string> test_list;
test_list.push_back("item11");
test_list.push_back("item21");
event_properties.SetList("test_list1", test_list);//数组
ThinkingAnalyticsAPI::Track("CPP_event", event_properties);
  • 事件的名称是字符串类型,只能以字母开头,可包含数字,字母和下划线 "_",长度最大为 50 个字符。
  • 事件属性是 TDJSONObject 类型,其中每个元素代表一个属性;
    • 事件属性 Key 为属性名称,为字符串类型,规定只能以字母开头,包含数字,字母和下划线 "_",长度最大为 50 个字符,对字母大小写不敏感;
    • 属性值支持字符串、数字、布尔、数组、时间类型。

用户属性的要求与事件属性保持一致

# 3.3 设置用户属性

对于一般的用户属性,您可以调用UserSet 来进行设置,使用该接口上传的属性将会覆盖原有的属性值,如果之前不存在该用户属性,则会新建该用户属性,类型与传入属性的类型一致,此处以设置用户名为例:

TDJSONObject userProperties;
userProperties.SetString("user_name", "TA");
ThinkingAnalyticsAPI::UserSet(userProperties);

# 四、最佳实践

以下示例代码包含以上所有操作,我们推荐按照如下步骤使用:

#include "ta_analytics_sdk.h"
using namespace thinkingdata;
//初始化SDK
ThinkingAnalyticsAPI::Init(SERVER_URL, APPID);
 //如果用户已登录,可以设置用户的账号ID作为身份唯一标识
ThinkingAnalyticsAPI::Login("TA");
//发送事件
TDJSONObject event_properties;
event_properties.SetString("name1", "name1");//字符串
event_properties.SetNumber("test_number_int", 3);//数字
event_properties.SetBool("test_bool", true);//bool
event_properties.SetDateTime("test_time1", time(NULL), 0);//时间
std::vector<std::string> test_list;
test_list.push_back("item11");
test_list.push_back("item21");
event_properties.SetList("test_list1", test_list);//数组
ThinkingAnalyticsAPI::Track("CPP_event", event_properties);;
//设置用户属性
TDJSONObject userProperties;
userProperties1.SetString("user_name", "TA");
ThinkingAnalyticsAPI::UserSet(userProperties);

#

#

#