C++ SDK 用户属性上报

说明如何使用 Gravity Engine C++ SDK 设置、追加、累加和删除用户属性，并提供参数要求与调用示例。

本文档详细介绍了SDK提供的用户属性上报功能，帮助开发者高效地收集、更新和维护用户画像数据。

通过本功能，您可以：

全面记录用户特征：存储用户基础信息（如昵称、性别）、行为偏好等关键数据
灵活更新用户画像：支持覆盖、追加、数值计算等多种更新方式
构建精准用户模型：通过属性组合分析，实现用户分群和个性化服务

如需上报自定义的用户属性，您必须先在元数据中添加对应的用户属性，否则会上报失败！

1. 设置用户属性

对于一般的用户属性，您可以调用 user_set 来进行设置，使用该接口上传的属性将会覆盖原有的属性值。

GEPropertiesNode u;
u.SetString("username", "Alice");
GEAnalytics::user_set(u);

2. 初始化用户属性

如果您要上传的用户属性只要设置一次，则可以调用 user_set_once 来进行设置，当该属性之前已经有值的时候，将会忽略这条信息。

GEPropertiesNode r;
r.SetString("register_date", "2026-01-01");
GEAnalytics::user_set_once(r);

3. 累加用户属性

当您要上传数值型的属性时，您可以调用 user_increment 来对该属性进行累加操作，可传入负值，等同于相减操作。

GEPropertiesNode n;
n.SetNumber("coins", 100);
GEAnalytics::user_increment(n);

设置的属性 key 为字符串，Value 只允许为数值。

4. 重置用户属性

如果您需要重置用户的某个属性，可以调用 user_unset 将该用户指定用户属性的值重置。

GEPropertiesNode n;
n.SetNumber("coins", 0); // value 固定为 0
GEAnalytics::user_unset(n);

user_unset 的传入 key 值为被重置属性的名称，value 固定为 0。

5. 清空用户属性

如果您要删除某个用户，可以调用 user_del 将这名用户删除，您将无法再查询该名用户的用户属性，但该用户产生的事件仍然可以被查询到。

GEAnalytics::user_del();

6. 用户属性追加（Array）

您可以调用 user_append 对 Array (List) 类型的用户数据追加元素。

GEPropertiesNode list_props;
std::vector<std::string> tags = {"vip", "new"};
list_props.SetList("tags", tags);
GEAnalytics::user_append(list_props);

7. 用户属性去重追加（Array）

user_uniq_append 用来对 Array (List) 类型的用户数据去重追加元素。

GEPropertiesNode list_props;
std::vector<std::string> tags = {"vip", "new"};
list_props.SetList("tags", tags);
GEAnalytics::user_uniq_append(list_props);

用户属性上报