SDK 1.x 版本至 2.x 版本升级指导

首先,欢迎您选择升级至 2.x 版本。在 2.x 版本内,您会体验到更加强大的自定义数据分析,帮助您将自有数据与 GrowingIO 采集的行为数据打通分析。

如果您目前使用的是 1.x 版本的 SDK,希望升级至 2.x 版本,请注意:您需要联系您的 GrowingIO 对接人,我们需要帮您开启后台 2.x 版本所对应功能。如果您直接集成 2.x 版本,而后台对应功能未开启的话,可能会造成数据丢失的问题。

本文旨在帮助您从 1.x 版本无缝升级至 2.x 版本,由于两个版本的诸多接口、方法、字段含义均有较大变动,因此建议您在升级前一定参照本文完成必要的实施工作。

升级步骤

要完成从 1.x 版本至 2.x 版本的升级,您需要完成以下几个步骤:

1. 重新集成 SDK

请您参考以下开发文档,完成SDK初始化代码的添加。

Tips:建议您在开发中,使用 debug mode 校验 GrowingIO SDK 的数据是否正常上传。开启 debug mode 的方式请见上述文档中初始化方法部分。

2. 迁移用户属性字段(CS字段)

如果您未做用户属性字段上传,请忽略此部分。

用户属性字段(简称CS字段)是 1.x 版本的概念,升级至 2.x 版本后:

  • CS1字段,会强制命名为“登陆用户ID”,并且上传接口与其他变量不同。
  • CS2-10字段,会迁移至“应用级变量”,应用级变量与CS字段的使用方式无任何区别。
  • CS11-20字段,会迁移至“用户变量”。两者的区别主要在于:用户变量支持自定义的归因方式。

2.1 上传接口:

2.x 版本中的上传用户变量方法有较大改动,不再将 'setCSn' 这个字段作为参数,方法中只需写入用户变量的 key - value 对。

Web 端:

  • 1.x 版本方法格式:
_vds.push(['setCS1', 'CS1的key', 'CS1的value']);
_vds.push(['setCS2', 'CS2的key', 'CS2的value']);
_vds.push(['setCS3', 'CS3的key', 'CS3的value']);
...
_vds.push(['setCS10', 'CS10的key', 'CS10的value']);
  • 2.x 版本方法格式:

对于 CS1 字段,也就是登陆用户ID,请使用以下方法:

// 设置登录用户ID
gio('setUserId', userId); 

// 清除登录用户ID
gio('clearUserId');

对于应用级变量,也就是 1.x 版本中的 CS2 - CS10,请使用以下方法:

gio(‘app.set’, key, value) // 单个变量
gio('app.set', appLevelVariables) // 多个变量,可组合为一个JSON对象appLevelVariables传入

对于用户变量,也就是 1.x 版本中的 CS11 - CS20,请使用以下方法:

gio('people.set', key, value); // 单个变量
gio('people.set', peopleVariables); // 多个变量,可组合为一个JSON对象peopleVariables传入

Android 端:

  • 1.x 版本方法格式:
GrowingIO growingIO = GrowingIO.getInstance();
    growingIO.setCS1("user_id", "100324");
    growingIO.setCS2("company_id", "943123");
    growingIO.setCS3("user_name", "张溪梦");
  • 2.x 版本方法格式:

对于 CS1 字段,也就是登陆用户ID,请使用以下方法:

// 设置登录用户ID API
GrowingIO.getInstance().setUserId(String userId);

// 清除登录用户ID API
GrowingIO.getInstance().clearUserId();

对于应用级变量,也就是 1.x 版本中的 CS2 - CS10,请使用以下方法:

GrowingIO.setAppVariable(JSONObject variables)
GrowingIO.setAppVariable(String key, Number variable)
GrowingIO.setAppVariable(String key, String variable)
GrowingIO.setAppVariable(String key, Boolean variable)

对于用户变量,也就是 1.x 版本中的 CS11 - CS20,请使用以下方法:

GrowingIO gio = GrowingIO.getInstance();
gio.setPeopleVariable(String key, String value);
gio.setPeopleVariable(String key, Number value);
gio.setPeopleVariable(String key, Boolean value);
gio.setPeopleVariable(JSONObject peopleVariables);// 多个变量,可组合为一个JSON对象peopleVariables传入

iOS 端:

  • 1.x 版本方法格式:
[Growing setCS1Value:@"100324" forKey:@"user_id"];
[Growing setCS2Value:@"943123" forKey:@"company_id"];
[Growing setCS3Value:@"张溪梦" forKey:@"user_name"];
  • 2.x 版本方法格式:

对于 CS1 字段,也就是登陆用户ID,请使用以下方法:

// 设置登录用户ID API
+ (void)setUserId:(NSString *)userId;

// 清除登录用户ID API
+ (void)clearUserId;

对于应用级变量,也就是 1.x 版本中的 CS2 - CS10,请使用以下方法:

[Growing setAppVariable:@{@"key1":@"value1", @"key2":@2}];
[Growing setAppVariableWithKey:@"key1" andStringValue:@"value1"];
[Growing setAppVariableWithKey:@"key2" andNumberValue:@2];

对于用户变量,也就是 1.x 版本中的 CS11 - CS20,请使用以下方法:

+ (void)setPeopleVariableWithKey:(NSString *)key andStringValue:(NSString *)stringValue;
+ (void)setPeopleVariableWithKey:(NSString *)key andNumberValue:(NSNumber *)numberValue;
+ (void)setPeopleVariable:(NSDictionary<NSString *, NSObject *> *)variable; // 多个变量,可组合为一个对象传入

2.2 GrowingIO 后台配置

在 GrowingIO 后台进行用户属性字段配置,是在 “项目配置” - “CS字段配置” 页面。升级至 2.x 版本后,取消了上述配置方式。您可以在 “管理” - “自定义事件和变量” 页面中的 “应用级变量” 和 “用户变量” Tab 页分别找到自动为您迁移过去的两种变量的配置。配置方式请参考相关帮助文档

3. 迁移页面属性字段(PS字段)

如果您未做页面属性字段上传,请忽略此部分。

类似于用户属性字段,在 2.x 版本中,页面属性字段被迁移到了“页面级变量”。与页面属性字段不同的是,页面级变量相当于过去的 PS 字段,不再存在过去的 PG 字段

3.1 上传接口

Web 端:

  • 1.x 版本方法格式:
_vds.push([’setPageGroup‘, ‘PageGroup 的名称’]; 
_vds.push([‘setPS1’, ‘PS1 的值’]); 
_vds.push([‘setPS2’, ‘PS2 的值’]); 
_vds.push([‘setPS3’, ‘PS1 的值’]);
  • 2.x 版本方法格式:
gio('page.set', key, value);
gio('page.set', pageLevelVariables); //多个变量,可组合为一个对象传入

Android 端:

  • 1.x 版本方法格式:
GrowingIO.setPageGroup(Activity activity, String name); 
GrowingIO.setPS1(Activity activity, String property); 
GrowingIO.setPS2(Activity activity, String property);
  • 2.x 版本方法格式:
GrowingIO gio = GrowingIO.getInstance();
gio.setPageVariable(Activity activity, String key, String value);
gio.setPageVariable(Activity activity, String key, Number value);
gio.setPageVariable(Activity activity, String key, Boolean value);
gio.setPageVariable(Activity activity, JSONObject pageLevelVariables);

gio.setPageVariable(Fragment fragment, String key, String value);
gio.setPageVariable(Fragment fragment, String key, Number value);
gio.setPageVariable(Fragment fragment, String key, Boolean value);
gio.setPageVariable(Fragment fragment, JSONObject pageLevelVariables);

iOS 端:

  • 1.x 版本方法格式:
@property (nonatomic, copy) NSString* growingAttributesPageGroup; 
@property (nonatomic, copy) NSString* growingAttributesPS1; 
@property (nonatomic, copy) NSString* growingAttributesPS2; 
@property (nonatomic, copy) NSString* growingAttributesPS3;
  • 2.x 版本方法格式:
+ (void)setPageVariableWithKey:(NSString *)key andStringValue:(NSString *)stringValue toViewController:(UIViewController *)viewController;

+ (void)setPageVariableWithKey:(NSString *)key andNumberValue:(NSNumber *)numberValue toViewController:(UIViewController *)viewController;

+ (void)setPageVariable:(NSDictionary<NSString *, NSObject *> *)variable toViewController:(UIViewController *)viewController;

2.2 GrowingIO 后台配置

您需要在 “管理” - “自定义事件和变量” 页面中的 “页面级变量” Tab 页进行配置。配置方式请参考相关帮助文档

4. 迁移自定义事件(埋点事件)

如果您未做自定义事件的上传,请忽略此部分。

2.x 版本的自定义事件,在概念上与 1.x 版本无任何区别,但上传接口和配置方式上有以下变更。

4.1 上传接口

Web 端:

  • 1.x 版本方法格式:
window._vds.track(event_name, properties)
  • 2.x 版本方法格式:
gio('track', eventId);
gio('track', eventId, number);
gio('track', eventId, eventLevelVariables);
gio('track', eventId, number, eventLevelVariables);

Android 端:

  • 1.x 版本方法格式:
public class GrowingIO {
    public GrowingIO track(String eventName, JSONObject properties)
}
  • 2.x 版本方法格式:
GrowingIO gio = GrowingIO.getInstance();
gio.track(String eventId);
gio.track(String eventId, Number eventNumber);
gio.track(String eventId, Number eventNumber, JSONObject eventLevelVariables);
gio.track(String eventId, JSONObject eventLevelVariables);

iOS 端:

  • 1.x 版本方法格式:
@interface Growing: NSObject
+ (void)track: (NSString *) event properties: (nullable NSDictionary *) properties;
@end
  • 2.x 版本方法格式:
+ (void)track:(NSString *)eventId;
+ (void)track:(NSString *)eventId withNumber:(NSNumber *)number;
+ (void)track:(NSString *)eventId withNumber:(NSNumber *)number andVariable:(NSDictionary<NSString *, NSObject *> *)variable;
+ (void)track:(NSString *)eventId withVariable:(NSDictionary<NSString *, NSObject *> *)variable;

4.2 GrowingIO 后台配置

自定义事件的配置,同 1.x 版本一样,也是在“管理” - “自定义事件和变量” 页面中的 “自定义事件” Tab 页。但您会发现,除了 “自定义事件” Tab 页外,现在还提供了 “事件级变量” Tab 页来专门管理事件级变量的配置。您只需在 “事件级变量” Tab 页完成事件级变量的配置,然后在新建自定义事件时,从已经建好的事件级变量中选择即可。

5. 数据校验

在完成了上述代码实施和配置后,我们当然需要对数据是否成功上传进行校验。校验工作分为两步完成。

数据校验第一步:本地开发环境校验

GrowingIO 提供了 SDK debug 模式以及 debug 工具,来帮助您完成数据的校验。

  1. Web 端

对 Web 端的开发者,GrowingIO 提供了 Chrome 浏览器插件形式的 debug 工具,请在这里下载安装。

debug 工具的工作界面如下图:

log 中自定义数据的关键字

  • 在 cstm 条目中,可以看到上传的 “自定义事件+事件级变量” 数据
  • 在 pvar 条目中,可以看到上传的 “页面级变量” 数据
  • 在 evar 条目中,可以看到上传的 “转换变量” 数据
  • 在各条目中,都可以找到 “用户变量” 对应的数据
  • 移动端

对移动端的开发者,GrowingIO 的 SDK 提供了 debug 模式,在 SDK 初始化代码中可以找到。如下图:

Android:

iOS:

开启 debug 模式后,您需要在app上触发一下打点事件,在打出的log里搜索上述关键字就能找到对应自定义事件&变量上传的数据。

数据校验第二步:GrowingIO 后台图表验证

在 GrowingIO 分析后台,找到 “单图” - “新建事件分析”,然后在图表中选择您设计好的 “指标+维度”,查看是否有数据。当然,您需要首先确保您的自定义事件或变量确实有被触发。