iOS集成开发指南

如需集成DeepShare,请参考DeapShare iOS 集成文档补充集成DeepShare内容。

一、安装SDK

最简单的安装方式是使用CocoaPods

  1. 若未安装CocoaPod,请先在终端执行 gem install cocoapods来安装CocoaPod

  2. 创建Podfile文件。若目录下没有Podfile文件,请在项目目录下执行pod init,若已有,请直接执行下一步

  3. 打开Podfile文件,按照如下示例,找到target为你的项目名称那一行,在其下一行添加Zhugeio

    target 'yourProjectName' do
    
    # Pods for your project
    pod 'Zhugeio'
    
    end
    
  4. 项目目录下执行pod install,CocoaPods会自动安装Zhuge SDK,并生成工作区文件*.xcworkspace,打开该工作区即可。

你也可以直接下载来安装:

  1. 下载SDK
  2. Zhugeio目录拖拽到项目中
  3. 安装所有依赖: UIKitFoundationlibz.tbd

二、兼容性和ARC

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

三、诸葛用户追踪ID方案

  1. 诸葛首选采用IDFA作为用户追踪的ID,这需要你的应用安装AdSupport依赖包。
  2. 如果你的应用中没有广告,采用IDFA可能会审核被拒,请在编译时加入ZHUGE_NO_ADID标志,诸葛将会采用IDFV作为追踪的ID。
    XCode设置方法:
    Build Settings > Apple LLVM 6.0 - Preprocessing > Processor Macros > Release : ZHUGE_NO_ADID=1
    
  3. 你也可以自己管理追踪ID。在初始化时,传入你自己定义的设备ID作为当前设备的追踪ID。 示例代码:

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

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

四、初始化

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

#import "Zhuge/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];

五、识别用户

为了保持对用户的跟踪,你需要为每一位用户记录一个唯一的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个字符计算。

六、自定义事件

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

    //定义与事件相关的属性信息  
    NSMutableDictionary *properties = [NSMutableDictionary dictionary];  
    properties[@"视频名称"] = @"冰与火之歌";
    properties[@"分类"] = @"奇幻";
    properties[@"时间"] = @"5:10pm";
    properties[@"来源"] = @"首页"; 
    //记录事件
    [[Zhuge sharedInstance] track:@"观看视频" properties:     properties];

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

七、时长事件的统计

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

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一致),单独调用一个接口是无效的。

八、在UIWebView中进行统计

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

  • Objective C代码集成

    首先要找到你的UIWevView的UIWebViewDelegate对象,并在webViewDidFinishLoad时做如下处理:

      #import <JavaScriptCore/JavaScriptCore.h>
      #import "ZhugeJS.h"
    
      -(void)webViewDidFinishLoad:(UIWebView *)webView{
    
      JSContext *jsContext = [webView valueForKeyPath:@"documentView.webView.mainFrame.javaScriptContext"];
    
      jsContext[@"zhugeTracker"] = [[ZhugeJS alloc] init];
    
      jsContext.exceptionHandler = ^(JSContext *context, JSValue *exceptionValue) {
          context.exception = exceptionValue;
          NSLog(@"异常信息:%@", exceptionValue);
      };
    }
    
  • js代码统计

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

九、在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];
    
  • JS代码集成

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

十、设置自定义属性

  • 事件自定义属性
 [Zhuge setSuperProperty:(NSDictionary *) pro];

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

十一、自定义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;

十二、 崩溃采集

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

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

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

注:

  1. 如果你同时使用了Bugly,可以兼容一起使用采集崩溃信息;

  2. 如果你同时使用了其他崩溃采集工具或自己采集,请测试兼容性;

  3. 如遇到问题,请随时联系我们。

十三、iOS 视屏数据采集

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

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

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

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

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

十四、其他可选API

  1. 你可以通过这个接口来获取当前设备在诸葛体系下的设备标识 。 [[Zhuge sharedInstance] getDid]

  2. 你可以通过这个接口来获得当前应用所属的会话ID。 [[Zhuge sharedInstance] getSid]

  3. 实时调试:你可以使用诸葛io提供的实时调试功能来查看实时布点数据,并确认是否准确。

    使用方法:在诸葛统计初始化之前,调用如下代码,以开启实时调试(注意:建议仅在测试设备上开启):

    [[Zhuge sharedInstance] setDebug:YES]

    然后在诸葛io中打开实时调试页面,即可实时查看上传的数据.

日志输出

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

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

©zhugeio.com 京ICP备15049545号            文档更新时间 2018-10-23 16:29:16

results matching ""

    No results matching ""