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'

若需要支持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以embeded binary形式添加进去。

2. SDK的基础调用

2.1 获取SDK配置信息

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

2.2 配置并获取SDK对象

2.2.1 添加头文件

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

@import Sugo;

若使用支持Weex可视化埋点功能的SDK时，出现问题，可替代使用：

#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 Types

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

Identifier: Sugo
URL Schemes: sugo.* (“*”位置替换成Token)
Icon: (可随意)
Role: Editor

2.3.1.2 选择被调用的API

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

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)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 注册

当每一个事件都需要记录相同的属性时，可以选择使用全局属性(全局属性仅允许NSString类型作为key值，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 Types

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`拖到你的项目（或工作空间）中