iOS Objective-C SDK

优质

小牛编辑

134浏览

2023-12-01

如需集成DeepShare，请参考DeepShare iOS集成
1. 导入SDK

你可以用下面的方法进行导入：

方法1. 使用CocoaPods导入

若未安装CocoaPod，请先在终端执行 gem install cocoapods来安装CocoaPod
创建Podfile文件。若目录下没有Podfile文件，请在项目目录下执行pod init，若已有，请直接执行下一步
打开Podfile文件，按照如下示例，找到target为你的项目名称那一行，在其下一行添加ZhugeioAnalytics
```
target 'yourProjectName' do

# Pods for your project
pod 'ZhugeioAnalytics'

end
```
项目目录下执行pod install，CocoaPods会自动安装Zhuge SDK，并生成工作区文件*.xcworkspace，打开该工作区即可。

方法2. 直接下载来安装：

下载SDK：
把Zhugeio目录拖拽到项目中
安装所有依赖： UIKit、Foundation、libz.tbd

2. 兼容性和ARC

诸葛SDK仅支持iOS 7.0以上系统，你需要使用Xcode 5和IOS 7.0及以上开发环境进行编译，如果你的版本较低，强烈建议升级。
诸葛SDK默认采用ARC，如果你的项目没有采用ARC，你需要在编译(Build Phases -> Compile Sources)时，为每个Zhuge文件标识为-fobjc-arc。

3. 诸葛用户追踪ID方案

诸葛首选采用IDFA作为用户追踪的ID，这需要你的应用安装AdSupport依赖包。
如果你的应用中没有广告，采用IDFA可能会审核被拒，请在编译时加入ZHUGE_NO_ADID标志，诸葛将会采用IDFV作为追踪的ID。
XCode设置方法:
```
Build Settings > Apple LLVM 6.0 - Preprocessing > Processor Macros > Release : ZHUGE_NO_ADID=1
```

你也可以自己管理追踪ID。在初始化时，传入你自己定义的设备ID作为当前设备的追踪ID。示例代码：

    #import "Zhuge.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
     Zhuge *zhuge = [Zhuge sharedInstance];
    [zhuge startWithAppKey:@"Your App Key"  andDid:@"did" launchOptions:launchOptions];
}

注意： 上面的代码与下节中初始化的代码互相冲突，请只调用一种。上面的代码即完成了SDK初始化动作。

4. 初始化

用应用的AppKey启动诸葛io SDK。

#import "Zhuge.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [[Zhuge sharedInstance] startWithAppKey:@"Your App Key" launchOptions:launchOptions];
}

如果你需要修改SDK的默认设置，如设置版本渠道时，一定要在startWithAppKey前执行；代码如下：

    Zhuge *zhuge = [Zhuge sharedInstance];

    // 实时调试开关
    // 设置为YES，可在诸葛io的「实时调试」页面实时观察事件数据上传
    // 建议仅在需要时打开，调试完成后，请及时关闭
    [zhuge.config setDebug : NO];

    // 自定义应用版本
    [zhuge.config setAppVersion:@"0.9-beta"]; // 默认是info.plist中CFBundleShortVersionString值

    // 自定义渠道
    [zhuge.config setChannel:@"My App Store"]; // 默认是@"App Store"

    // 开启行为追踪
    [zhuge startWithAppKey:@"Your App Key" launchOptions:launchOptions];

延迟采集

如果需要将诸葛默认获取的mac,Android_id，imei等延迟采集。 iOS 请在获取权限后的第一个UIController 初始化 SDK

[[Zhuge sharedInstance] startWithAppKey:@"fac6c5d6081b463183e721a44ebbb5d2" launchOptions:nil];

5. 识别用户

为了保持对用户的跟踪，你需要为每一位用户记录一个唯一的ID，你可以使用用户id、email等唯一值来作为用户在诸葛io的ID。另外，你可以在跟踪用户的时候，记录用户更多的属性信息，便于你更了解你的用户：

    //定义诸葛io中的用户ID
    NSString *userId = [user getUserId]

    //定义属性
    NSMutableDictionary *userInfo = [NSMutableDictionary dictionary];
    userInfo[@"name"] = @"zhuge";
    userInfo[@"gender"] = @"男";
    userInfo[@"birthday"] = @"2014/11/11";
    userInfo[@"avatar"] = @"http://tp2.sinaimg.cn/2885710157/180/5637236139/1";
    userInfo[@"email"] = @"hello@zhuge.io";
    userInfo[@"mobile"] = @"18901010101";
    userInfo[@"qq"] = @"91919";
    userInfo[@"weixin"] = @"121212";
    userInfo[@"weibo"] = @"122222";
    userInfo[@"location"] = @"北京朝阳区";
    userInfo[@"公司"] = @"37degree";
    [[Zhuge sharedInstance] identify:userId properties:userInfo];

长度限制:Key最长支持25个字符，Value最长支持255个字符，一个汉字按3个字符计算。

6. 自定义事件

你可以在startWithAppKey之后开始记录事件（用户行为），并可记录与该事件相关的属性信息

    //定义与事件相关的属性信息  
    NSMutableDictionary *properties = [NSMutableDictionary dictionary];  
    properties[@"分类"] = @"手机";
    properties[@"型号"] = @"iPhone6 plus 64g";
    properties[@"价格"] = @5888;//数值型属性不要带引号
    //记录事件
    [[Zhuge sharedInstance] track:@"购买" properties:     properties];

注意：在添加事件属性时，需注意事件属性类型。如果事件属性类型为「数值型属性」，需要在上传数据时修改数据类型为「数值型」，并且在诸葛io后台埋点管理中修改为「数值型」。

7. 时长事件的统计

若你希望统计一个事件发生的时长，比如视频的播放，页面的停留，那么可以调用如下接口来进行：

Zhuge *zhuge = [Zhuge sharedInstance];
NSString *eventName = @"";
[zhuge startTrack:eventName];

说明：调用startTrack来开始一个事件的统计，eventName为一个事件的名称

Zhuge *zhuge = [Zhuge sharedInstance];
NSString *eventName = @"";
NSDictionary *pro = [NSDictionary dictionary];
[zhuge endTrack:eventName properties:pro];

说明：调用endTrack来记录事件的持续时长。调用endTrack之前，相同eventName的事件必须已经调用过startTrack，否则这个接口不会产生任何事件。

代码示例：

Zhuge *zhuge = [Zhuge sharedInstance];
NSString *eventName = @"观看视频";

//视频播放开始
[zhuge startTrack:eventName];

//视频观看结束
NSDictionary *pro = [NSDictionary dictionary];
pro[@"名称"] = @"非诚勿扰";
pro[@"期数"] = @"2016-11-02";
[zhuge endTrack:eventName properties:pro];

注意：startTrack与endTrack必须成对出现（eventName一致），单独调用一个接口是无效的。

8. 在WKWebView中进行统计

如果你的页面中使用了WKWebView嵌入HTML,js 的代码，并且希望统计HTML中的事件，那么可以通过下面的文档来进行跨平台的统计。注意如果你的HTML是运行在浏览器的，那么还是无法统计的，下文仅针对使用WKWebView加载网页的情况。

Objective C代码集成

在你的WKWebView对象初始化时，为其配置一个WKWebViewConfiguration对象，对象的具体配置如下：

  #import "ZhugeJS.h"

  //初始化一个WKWebViewConfiguration
  WKWebViewConfiguration *config = [[WKWebViewConfiguration alloc]init];

  //初始化一个WKUserContentController
  WKUserContentController* userContent = [[WKUserContentController alloc] init];

  //给WKUserContentController设置一个js脚本控制器
  [userContent addScriptMessageHandler:[[ZhugeJS alloc]init] name:@"zhugeTracker"];

  //将配置过脚本控制器的WKUserContentController设置给WKWebViewConfiguration
  config.userContentController = userContent;

  //使用配置好的WKWebViewConfiguration，创建WKWebView
  self.webView =[[WKWebView alloc]initWithFrame:frame configuration:config];

  // 配置UserAgent
  __block NSString *newUserAgent_WK;
  __block NSDictionary *dictionary;
  [self.webView evaluateJavaScript:@"navigator.userAgent" completionHandler:^(id result, NSError *error) {
  if (!error) {
      newUserAgent_WK = [result stringByAppendingString:@" ZGSDK"];
      dictionary = [NSDictionary dictionaryWithObjectsAndKeys:newUserAgent_WK, @"UserAgent", nil];
      [[NSUserDefaults standardUserDefaults] registerDefaults:dictionary];
  } else {
      NSLog(@"设置ZGUserAgent失败 == %@",error);
  }
  }];

3.4.15版本之后支持自动打通H5，调用如下方法：

  [Zhuge sharedInstance].config.enableJavaScriptBridge = YES;

JS代码集成
Native端配置好之后，即可在html页面中通过js进行移动端的打点，具体统计方式请参照JS集成文档，JS的sdk会自动判断页面来自浏览器或APP，区分事件所属平台。

9. 设置自定义属性

事件自定义属性

 [Zhuge setSuperProperty:(NSDictionary *) pro];

若有一些属性，每一个事件都要拥有，那么你可以调用setSuperProperty传入，之后，每一个经过track,endTrack传入的事件，都将自动获得这些属性。

10. 自定义SDK数据上传规则

诸葛io支持自己定义SDK数据上传规则，具体的可定义信息及定义方式如下：

配置位置：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    Zhuge *zhuge = [Zhuge sharedInstance];

    zhuge.config.sendInterval = 20; //上报时间间隔。
    zhuge.config.cacheMaxSize = 300; //本地最大记录缓存数。
    zhuge.config.sendMaxSizePerDay = 1000; //每日最大上传记录数。

    [zhuge startWithAppKey:@"App Key" launchOptions:launchOptions];

}

1.数据上传间隔，此项指定若上传未完成，多少秒后重试上传。整数类型，默认为5秒。

//上报时间间隔。
[Zhuge sharedInstance].config.sendInterval = 20;

2.本地最大记录缓存数，此项指定若无网络或请求失败，本地最大可缓存的记录数。整数类型，默认为500条。

//本地最大记录缓存数。
[Zhuge sharedInstance].config.cacheMaxSize = 300;

3.每日最大上传记录数，为减少用户流量消耗，此项指定每日每设备最大可上传的事件数。整数类型，默认为500条。

//每日最大上传记录数。
[Zhuge sharedInstance].config.sendMaxSizePerDay = 1000;

11. iOS 全埋点

全埋点功能默认为关闭，集成SDK后打开全埋点开关，即可采集页面访问、页面点击；调用方法如下：

[[Zhuge sharedInstance] enableAutoTrack];

页面点击默认采集内置属性。

$page_title：页面标题
$eid"：全埋点类型 click / pv
$element_content：控件的文本内容
$element_type：控件的类型
$element_selector：控件的选择器

12. 崩溃采集

如果希望采集应用崩溃信息，你需要打开崩溃采集开关，默认为关闭。在SDK初始化之前调用如下方法：

    Zhuge *zhuge = [Zhuge sharedInstance];
    [zhuge.config setExceptionTrack:YES]; //开启崩溃统计
    [zhuge startWithAppKey:@"Your App Key" launchOptions:launchOptions];

崩溃采集信息包括：异常名称、异常描述、发生时间、应用版本、应用包名等信息。

注：

如果你同时使用了Bugly，可以兼容一起使用采集崩溃信息；
如果你同时使用了其他崩溃采集工具或自己采集，请测试兼容性；
如遇到问题，请随时联系我们。

13. iOS 视屏数据采集

视屏数据默认为不采集，如需采集某个用户的视屏数据，可在需要采集该用户视屏数据时，调用如下方法：

  Zhuge *zhuge = [Zhuge sharedInstance];
  [zhuge.config setZgSeeEnable:YES];

如需关闭采集该用户的视屏数据时，调用如下方法：

  Zhuge *zhuge = [Zhuge sharedInstance];
  [zhuge.config setZgSeeEnable:NO];

注：视屏采集数量有限制，建议仅采集需要观察、分析的用户的视屏数据。

14. 收入数据采集

收入数据采集，需调用trackRevenue函数，自动记录收入事件以及事件属性；price(商品价格)、productID(商品ID)、productQuantity(商品数量)、revenueType(收入类型)为收入事件内置属性，必传项。

具体使用方法如下：

[[Zhuge sharedInstance] trankRevenue:@{ZhugeEventRevenuePrice:@229,     //数值型属性不要带引号
                                           ZhugeEventRevenueProductID:@"小米NFC手环",
                                           ZhugeEventRevenueProductQuantity:@2, //数值型属性不要带引号
                                           ZhugeEventRevenueType:@"手环",
    }];

15. 页面停留时长采集

你可以通过以下方法来进行页面停留时长的数据采集，调用这个方法后，我们会自动帮您采集应用上的页面停留时长数据。

[[Zhuge sharedInstance] enabelDurationOnPage];

16. 元素曝光采集

曝光采集功能默认关闭，需要在SDK调用Init之前进行开启

[[Zhuge sharedInstance] enableExpTrack];

标记需要曝光采集的元素一般而言，在view初始化之后调用如下方法进行标记

[self.button zhugeioExpTrack:@"your event id"];

关于参数 zhugeioExpTrack

参数	是否必须	说明
eventId	必须	事件名称
variable	非必须	曝光时对应的事件属性

1、追踪 UIButton 代码示例:

self.button = [[UIButton alloc] initWithFrame:CGRectMake(20, 250, 100, 35)];
[self.button setTitle:@"Button" forState:UIControlStateNormal];
[self.button zhugeioExpTrack:@"your event id" withVariable:@{@"tempkey0":@"tempvalue0"}];

2、追踪列表某一行

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {

    XSImageCell *item = [collectionView dequeueReusableCellWithReuseIdentifier:@"ImageCell" forIndexPath:indexPath];

    if (indexPath.item == 0) {
        [item zhugeioExpTrack:@"your evnet id"];
    } else {
        [item zhugeioStopExpTrack];
    }

    return item;
}

3、追踪列表全部行

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    XSImageCell *item = [collectionView dequeueReusableCellWithReuseIdentifier:@"ImageCell" forIndexPath:indexPath];

    [item zhugeioExpTrack:@"your evnet id"];

    return item;
}

17. 其他可选API

你可以通过这个接口来获取当前设备在诸葛体系下的设备标识。 [[Zhuge sharedInstance] getDid]
你可以通过这个接口来获得当前应用所属的会话ID。 [[Zhuge sharedInstance] getSid]
实时调试：你可以使用诸葛io提供的实时调试功能来查看实时布点数据，并确认是否准确。
使用方法：在诸葛统计初始化之前，调用如下代码，以开启实时调试（注意：建议仅在测试设备上开启）：
[[Zhuge sharedInstance].config setDebug:YES];
然后在诸葛io中打开实时调试页面，即可实时查看上传的数据.

日志输出

要在xcode控制台查看诸葛io SDK输入的日志，请在最新版的xcode中设置：

Build Settings > Apple Clang - Preprocessing > Preprocessor Macros > Debug : ZHUGE_LOG=1

SDK版本3.4.8以上请使用此api：

[Zhuge sharedInstance].config.enableLoger = YES;