iOS集成文档

如需集成DeepShare,需集成DeepShare内容。

一、导入SDK

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

方法1.使用CocoaPods导入

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

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

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

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

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

  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.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.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[@"型号"] = @"iPhone6 plus 64g";
    properties[@"价格"] = @5888;//数值型属性不要带引号
    //记录事件
    [[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];

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

十四、收入数据采集

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

具体使用方法如下:

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

十五、集成DeepShare

1.配置*-info.plist文件

添加用户打开APP的URL Scheme

添加一个叫URL types的键值

  1. 添加一个叫URL types的键值。
  2. 点击左边剪头打开列表,可以看到Item 0,一个字典实体。
  3. 点击Item 0新增一行,从下拉列表中选择URL Schemes,敲击键盘回车键完成插入。
  4. 更改所插入URL Schemes的值为DeepShare配置中生成的Scheme。

2.1 配置开发者信息

  1. 登录developers.apple.com,点击按钮「Certificate, Identifiers & Profiles」,再点击「Identifiers」。

    image

  2. 确保开启「Associated Domains」,这个按钮在页面下方,如图所示:

    image

2.2 配置Xcode

  1. 在Xcode配置中开启「Associated Domains」。

    • 选择相应的target;
    • 点击「Capabilities tab」;
    • 开启Associated Domains;
    • 点击「+」按钮,添加一个Associated Domain,其内容为applinks:zhugeapi.com 完成后,如图所示:

      image

  2. 在Xcode中添加依赖库。

    • 选择相应的target;
    • 选择Build Phrases;
    • 在Link Binary With Libraries中添加SafariServices.framework。

2.3 添加以下代码到AppDelegate

// Availability : iOS (9.0 and later)
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *))restorationHandler 
{
    //此处添加以下代码
    BOOL handledByDeepShare = [Zhuge continueUserActivity:userActivity];
    return handledByDeepShare;
}

2.4 添加调用代码

添加处理代码。

// Availability : iOS (9.0 and later)
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary *)options 
{
    //此处添加以下代码
    if([Zhuge handleURL:url]){
        return YES;
    }
    return NO;
}

如果是iOS8和以下版本,请用以下代码:

// Availability : iOS (4.2 to 8.4)
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(nullable NSString *)sourceApplication annotation:(id)annotation {
    //此处添加以下代码
    if([Zhuge handleURL:url]){
        return YES;
    }
    return NO;
}

2.5 获取场景还原参数

为实现场景还原功能,在AppDelegate的didFinishLaunchingWithOptions方法中添加[zhuge startWithAppKey… …]的调用,并通过Delegate接受返回的启动参数。 LaunchOptions是用来判断App是否是通过URL Scheme进行唤起的。

示例代码如下:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions{

    Zhuge *zhuge = [Zhuge sharedInstance];
    [zhuge startWithAppKey:@"此处填写您生成的应用appKey" launchOptions:launchOptions withDelegate:self];
    return YES;

}
- (void)zgOnInappDataReturned:(NSDictionary *)params withError:(NSError *)error 
{
    if (!error) 
    {
        NSLog(@"finished init with params = %@", [params description]);
        NSString *cmdName = [params objectForKey:@"name"];
        goToLinuxCmd(cmdName); //调用应用自己的接口跳转到分享时页面
    } else {
        NSLog(@"init error id: %ld %@",error.code, errorString);
    }
}

十六、其他可选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号            文档更新时间 2020-01-08 11:27:04

results matching ""

    No results matching ""