sugo-objc-sdk

介绍

欢迎使用由sugo.io提供的iOS端Objective-C版用户行为采集和分析。

sugo-objc-sdk是一个开源项目，我们非常期待收到的代码贡献。

1. 集成

1.1 CocoaPods

目前我们的发布版本仅支持通过Cocoapods 1.1.0及更高版本进行集成

通过CocoaPods，您可以方便地在项目中集成此SDK。

1.1.1 配置`Podfile`

请确保在项目根目录下的Podfile 文件（如果没有，请创建或从我们提供的SugoDemo目录中获取并做出相应修改）中添加以下内容：

pod 'sugo-objc-sdk'

若需要支持< fuerte> Weex 的可视化埋点功能，请完全替换上述内容。

pod 'sugo-objc-sdk/weex'

1.1.2 执行集成命令

关闭Xcode，在Podfile目录下执行以下命令：

pod install

1.1.3 完成

运行完毕后，打开集成后的xcworkspace文件即可。

1.2 手动安装

为了帮助开发者集成最新且稳定的SDK，我们建议通过Cocoapods来集成，这不仅简单而且易于管理。但是，为了便于其他集成情况，我们也提供手动安装此SDK的方法。

1.2.1 以子模块的形式添加

将sugo-objc-sdk以子模块的形式添加到本地库中

git submodule add [email protected]:Datafruit/sugo-objc-sdk.git

现在库中可以找到Sugo项目文件Sugo.xcodeproj。

1.2.2 把`Sugo.xcodeproj`拖到你的项目（或工作空间）中

将Sugo.xcodeproj拖到需要集成的项目文件中。

1.2.3 嵌入框架（Embed the framework）

选择需要集成此SDK的项目target，将Sugo.framework以嵌入二进制形式添加。

2. SDK的基础调用

2.1 获取SDK配置信息

登录数果星盘后，您可以在平台界面中创建项目和数据接入方式，创建数据接入方式时，即可获取项目ID与Token。

2.2 配置并获取SDK对象

2.2.1 添加头文件

在集成了SDK的项目中，打开AppDelegate.m，在文件头部添加：

@import Sugo;

如果您使用的SDK支持Weex可视化埋点功能并出现问题，可以替换使用：

#import "Sugo.h"
#import "Sugo+Weex.h"

2.2.2 添加SDK对象初始化代码

将以下代码复制到AppDelegate.m中，并填入已获得的项目ID与Token：

- (void)initSugo {
	NSString *projectID = @"Add_Your_Project_ID_Here";
	NSString *appToken = @"Add_Your_App_Token_Here";
	[Sugo sharedInstanceWithID:projectID token:appToken launchOptions:nil];
	[[Sugo sharedInstance] setEnableLogging:YES];	// 如果需要查看SDK的Log，请设置为true
	[[Sugo sharedInstance] setFlushInterval:5]; 	// 被绑定的事件数据往服务端上传的时间间隔，单位是秒，如若不设置，默认时间是60秒
	[[Sugo sharedInstance] setCacheInterval:60]; 	// 从服务端拉取绑定事件配置的时间间隔，单位是秒，如若不设置，默认时间是1小时
    // [[Sugo sharedInstance] registerModule];		// 需要支持Weex可视化埋点时调用
}

2.2.3 调用SDK对象初始化代码

在添加了initSugo后，在AppDelegate方法中调用，如下：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// Override point for customization after application launch.
	[self initSugo];	//调用 `initSugo`
	return YES;
}

2.3 扫码进入可视化埋点模式

2.3.1 通过扫码App进行扫码

2.3.1.1 配置App的URL类型

在Xcode中，点击App的xcodeproj文件，进入info标签页，添加URL Types。

Identifier: Sugo
URL Schemes: sugo.* （“*”处替换成Token)
图标: （可随意)
角色: 编辑器

2.3.1.2 选择被调用的API

UIApplicationDelegate中有3个可通过URL打开应用的方法，如下：

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary *)options;
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation;
- (BOOL)application:(UIApplication *)application handleOpenURL:(NSURL *)url;

请根据应用需适配的版本在AppDelegate.m中实现其中一个或多个方法。

2.3.1.3 可视化埋点模式API

在选定的方法中调用如下：

[[Sugo sharedInstance] handleURL:url];	//返回值为BOOL类型，可作为方法的返回值。

2.3.1.4 连接

登录数果星盘，进入对应Token的可视化埋点界面，可看见二维码，保持埋点设备网络畅通，通过设备任意可扫描二维码的应用扫描一扫，然后用Safari打开链接，点击网页中的链接，即可进入可视化埋点模式。此时设备上方将出现可视化埋点连接条，网页可视化埋点界面将显示设备当前页面及相应可绑定控件信息。

2.3.2 通过自身应用进行扫描

如果集成SDK的应用已把扫描功能开发完毕，也可通过自身的扫描功能进行可视化埋点模式的连接。即在扫描后，将已获取的URL作为参数，调用以下的方法：

- (void)connectToCodelessViaURL:(NSURL *)url;

该方法会对应用Token进行校验，若Token与初始化的值匹配，且已打开可视化埋点网页，则设备上方将出现可视化埋点连接条，网页可视化埋点界面将显示设备当前页面及相应可绑定控件信息，示例如下：

[[Sugo sharedInstance] connectToCodelessViaURL:url];	// url参数为扫描二维码后获得的值

2.4 绑定事件

2.4.1 原生控件

对于所有的UIView，都有一个NSString类型的sugoViewId属性，可以用于唯一指定容易混淆的可视化埋点视图，推荐在初始化时进行设置。

可以通过以下方式设置：

// #import <objc/runtime.h>
objc_setAssociatedObject(self, @selector(sugoViewId), @"CustomNSStringValue", OBJC_ASSOCIATION_RETAIN_NONATOMIC);

UIView

满足以下条件的UIView及其子类可以被可视化埋点绑定事件：

userInteractionEnabled属性为YES，且是UIControl或其子类。
userInteractionEnabled属性为YES，且gestureRecognizers数组属性中包含UITapGestureRecognizer或其子类的手势实例，且其enabled属性为YES。

UITableView

所有UITableView类及其子类，需要指定其delegate属性，并实现以下方法，方可被埋点绑定事件。基于UITableView运行原理的特殊性，埋点绑定事件时只需要整个区域，SDK会自动上报UITableView被选中的详细位置信息。

- (void)tableView:(UITableView *)tableView didSelectRowAtIndexPath:(NSIndexPath *)indexPath;

UICollectionView

所有UICollectionView类及其子类，需要指定其delegate属性，并实现以下方法，方可被埋点绑定事件。基于UICollectionView运行原理的特殊性，埋点绑定事件时只需要整个区域，SDK会自动上报UICollectionView被选中的详细位置信息。

- (void)collectionView:(UICollectionView *)collectionView didSelectItemAtIndexPath:(NSIndexPath *)indexPath;

2.4.2 UIWebView

所有UIWebView类及其子类下的网页元素，需要指定其delegate属性，并在指定的delegate类中实现以下方法：

- (BOOL)webView:(UIWebView *)webView shouldStartLoadWithRequest:(NSURLRequest *)request navigationType:(UIWebViewNavigationType)navigationType
- (void)webViewDidStartLoad:(UIWebView *)webView;
- (void)webViewDidFinishLoad:(UIWebView *)webView;

2.4.3 WKWebView

所有WKWebView类及其子类下的网页元素，均可被埋点绑定事件。

3. SDK的进阶调用

3.1 获取全局对象

通过单例模式获取全局可用的对象，如下：

Sugo *sugo = [Sugo sharedInstance];

3.2 手动埋点

3.2.1 代码埋点

当需要将自定义事件发送到服务器时，可在相应位置调用以下API

- (void)trackEvent:(NSString *)event;
- (void)trackEvent:(NSString *)event properties:(nullable NSDictionary *)properties;
- (void)trackEventID:(nullable NSString *)eventID eventName:(NSString *)eventName;
- (void)trackEventID:(nullable NSString *)eventID eventName:(NSString *)eventName properties:(nullable NSDictionary *)properties;

示例如下（根据需求调用）：

[[Sugo sharedInstance] trackEvent:@"EventName"];
[[Sugo sharedInstance] trackEvent:@"EventName" properties:@{ @"key1": @"value1", @"key2": @"value2"}];
[[Sugo sharedInstance] trackEventID:@"EventId" eventName:@"EventName"];	//eventId可为空
[[Sugo sharedInstance] trackEventID:@"EventId" eventName:@"EventName" properties:@{ @"key1": @"value2", @"key2": @"value2"}];	//eventId可为空

3.2.2 时长统计

3.2.2.1 创建

需要对时间进行跟踪统计时，可在开始跟踪的位置调用

- (void)timeEvent:(NSString *)event

示例如下：

[[Sugo sharedInstance] timeEvent:@"TimeEventName"];

3.2.2.2 发送

然后，在完成跟踪的位置调用3.2.1中的方法即可，需要注意的是eventName需要与开始时的一样，示例如下：

[[Sugo sharedInstance] trackEvent:@"TimeEventName"];

3.2.2.3 更新

在创建时间跟踪后，若想在发送前进行更新，只需再次以相同的时间事件名调用创建时的API，SDK就会刷新相同事件名的记录时间。

3.2.2.4 删除

若要清除所有时间跟踪事件，请调用以下方法：

- (void)clearTimedEvents;

示例如下：

[[Sugo sharedInstance] clearTimedEvents];

3.2.3 全局属性

3.2.3.1 注册

若每个事件都需要记录相同的属性，可以使用全局属性（全局属性的key值仅允许NSString类型，value值允许NSString、NSNumber、NSArray、NSDictionary、NSDate、NSURL等类型），通过调用以下方法：

- (void)registerSuperPropertiesOnce:(NSDictionary *)properties;
- (void)registerSuperProperties:(NSDictionary *)properties;

示例如下：

[[Sugo sharedInstance] registerSuperPropertiesOnce:@{ @"key1": @"value2", @"key2": @"value2"}]; // 此方法不会覆盖当前已有的全局属性
[[Sugo sharedInstance] registerSuperProperties:@{ @"key1": @"value2", @"key2": @"value2"}]; // 此方法会覆盖当前已有的全局属性

3.2.3.2 获取

要获取已注册的全局属性，可以调用以下方法：

- (NSDictionary *)currentSuperProperties;

示例如下：

[[Sugo sharedInstance] currentSuperProperties];

3.2.3.3 注销

若要注销某个全局属性，可以调用以下方法：

- (void)unregisterSuperProperty:(NSString *)propertyName;

示例如下：

[[Sugo sharedInstance] unregisterSuperProperty:@"SuperPropertyName"];

3.2.3.4 清除

要清除所有全局属性，请调用以下方法：

- (void)clearSuperProperties;

示例如下：

[[Sugo sharedInstance] clearSuperProperties];

3.2.3.5 跟踪用户首次登录

当需要跟踪用户首次登录用户账户时，可调用

- (void)trackFirstLoginWith:(nullable NSString *)identifer dimension:(nullable NSString *)dimension;

示例如下（其中dimension参数为用户已自定义的维度名）：

[[Sugo sharedInstance] trackFirstLoginWith:@"user_id" dimension: @"user_id_dimension"];

3.2.4 WebView埋点

当需要在WebView(UIWebView或WKWebView)中进行代码埋点时，在页面加载完毕后，可调用以下API（是3.2.1与3.2.2同名方法在JavaScript中的接口，实现机制相同）进行JavaScript内容的代码埋点

sugo.track(event_id, event_name, props);	// 准备把自定义事件发送到服务器时
sugo.timeEvent(event_name);					// 在开始统计时长的时候调用

3.2.5 Weex埋点

当需要在Weex(Vue)中进行代码埋点时，可调用以下API（是3.2.1与3.2.2同名方法在Weex中的接口，实现机制相同）进行JavaScript的代码埋点

let sugo = weex.requireModule('sugo');
sugo.track(event_name, props);				// 准备把自定义事件发送到服务器时
sugo.timeEvent(event_name);					// 在开始统计时长的时候调用

3.2.6 页面名称

当需要代码埋点管理页面名称是，可调用以下API进行页面名称的设置。

/* 设置每一个页面的页面名称需要传一个含字典的数组（“NSArray<NSDictionary *> *”类型），数据格式如下：
	[
		{
            "page": "ViewController", // 类名
            "page_name": "默认页面", // 页面名称
        },
        {
            "page": "/product/10244989633.html", // webview的path
            "page_name": "product10244989633", // 页面名称
        },
		...
	]

 */
- (void)setPageInfos:(NSArray<NSDictionary *> *)pageInfos;

4. 反馈

已经成功集成了此SDK了，想了解SDK的最新动态，请Star 或 Watch 我们的仓库： Github。

有问题解决不了？发送邮件到 [email protected] 或提出详细的issue，我们的进步，离不开各界的反馈。

sugo-objc-sdk 5.1.6

sugo-objc-sdk 5.1.6

sugo-objc-sdk 5.1.6

sugo-objc-sdk

介绍

1. 集成

1.1 CocoaPods

1.1.1 配置Podfile

1.1.2 执行集成命令

1.1.3 完成

1.2 手动安装

1.2.1 以子模块的形式添加

1.2.2 把Sugo.xcodeproj拖到你的项目（或工作空间）中

1.2.3 嵌入框架（Embed the framework）

2. SDK的基础调用

2.1 获取SDK配置信息

2.2 配置并获取SDK对象

2.2.1 添加头文件

2.2.2 添加SDK对象初始化代码

2.2.3 调用SDK对象初始化代码

2.3 扫码进入可视化埋点模式

2.3.1 通过扫码App进行扫码

2.3.1.1 配置App的URL类型

2.3.1.2 选择被调用的API

2.3.1.3 可视化埋点模式API

2.3.1.4 连接

2.3.2 通过自身应用进行扫描

2.4 绑定事件

2.4.1 原生控件

UIView

UITableView

UICollectionView

2.4.2 UIWebView

2.4.3 WKWebView

3. SDK的进阶调用

3.1 获取全局对象

3.2 手动埋点

3.2.1 代码埋点

3.2.2 时长统计

3.2.2.1 创建

3.2.2.2 发送

3.2.2.3 更新

3.2.2.4 删除

3.2.3 全局属性

3.2.3.1 注册

3.2.3.2 获取

3.2.3.3 注销

3.2.3.4 清除

3.2.3.5 跟踪用户首次登录

3.2.4 WebView埋点

3.2.5 Weex埋点

3.2.6 页面名称

4. 反馈

1.1.1 配置`Podfile`

1.2.2 把`Sugo.xcodeproj`拖到你的项目（或工作空间）中