iOS Swift集成开发指南

一、安装诸葛io SDK

通过CocoaPods安装:

  1. 打开终端,安装CocoaPod: gem install cocoapods
  2. 项目目录下创建podfile文件,并加入一行代码:pod 'Zhugeio'
  3. 项目目录下执行pod install,CocoaPods会自动安装 Zhuge SDK,并生成工作区文件 *.xcworkspace,打开该工作区即可。

你也可以选择手动导入:

  1. 下载SDK;
  2. 把Zhugeio目录拖拽到项目中;
  3. 安装所有依赖:UIKit、Foundation、ibz.tbd。

1.如何在Swift中调用OC的第三方类库?

在你pod或者手动导入SDK之后,我们需要创建一个bridging header文件(用于OC与Swift之间相互调用代码的.h文件):

  1. 「command+n」选取Header File

    image

  2. 注意头文件名字的命名规范:项目名称-Brdging-Header.h,如下图:

    image

  3. 新建完成后,使用#import来引用oc库,如下图:

    image

  4. 该步骤比较重要,选择 SexyGallery > Build Settings > 在搜索框输入 "Swift Compiler" > 双击 Objective-C Bridging Header > 直接把刚才的Header.h从工程拖入进来会生成这个文件的路径。

    image

  5. 之后我们就可以愉快在工程里调用第三方类库编写代码了。

    image

2. 初始化SDK

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

如果您需要修改SDK的默认设置,如设置版本渠道、开启实时调试、开启手势监听等时,一定要在startWithAppKey前执行。参考代码:

import Zhugeio

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplicationLaunchOptionsKey: Any]?) -> Bool {
        // Override point for customization after application launch.
        let zhuge = Zhuge.sharedInstance()

        //默认关闭实时调试 true打开
        zhuge.config().debug = true

        // 自定义渠道
        zhuge.config().channel = "My App Store" // 默认是@"App Store"

        // 开启行为追踪
        zhuge.start(withAppKey: "Your AppKey", launchOptions: launchOptions)// 请将「Your AppKey」替换为您应用的AppKey

        return true
    }

二、识别用户

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

//初始化两个变量 userid 和 自定义属性
var userid = "userId"
var userInfo = NSMutableDictionary()


//定义诸葛io中的用户ID
self.userid = "userId"
//定义属性
self.userInfo.setValue("zhuge", forKey: "name")
self.userInfo.setValue("男", forKey: "gender")
self.userInfo.setValue("2015/1/11", forKey: "birthday")
self.userInfo.setValue("http://tp2.sinaimg.cn/180/5637236139/1", forKey: "avatar")
self.userInfo.setValue("support@zhugeio.com", forKey: "email")
self.userInfo.setValue("18901010101", forKey: "mobile")
self.userInfo.setValue("91919", forKey: "qq")
self.userInfo.setValue("121212", forKey: "weixin")
self.userInfo.setValue("122222", forKey: "weibo")
self.userInfo.setValue("北京朝阳区", forKey: "location")
self.userInfo.setValue("37degree", forKey: "公司")

//跟踪用户
Zhuge.sharedInstance().identify(self.userid, properties: self.userInfo as [NSObject : AnyObject])

我们预定义了name、avatar用户属性,你可以直接使用:

属性key 说明
avatar 用户分析界面的头像
name 用户名

注意 :name和avatar属性为预定义属性,如果需要上传⽤户名或头像,请确保属性名无误;另,自定义的用户属性也不能与预定义的用户属性重复。

你也可以为用户添加所需的自定义属性,如:

self.userInfo.setValue("苹果", forKey: "喜欢的水果")
self.userInfo.setValue("女", forKey: "孩子的性别")

三、自定义事件

在你希望记录用户行为的位置,自定义事件,并可记录与该事件相关的属性信息,调用如下代码:

////定义与事件相关的属性信息  
var properties = NSMutableDictionary()

//定义与事件相关的属性信息
self.properties.setValue("冰与火之歌", forKey: "视频名称")
self.properties.setValue("奇幻", forKey: "分类")
self.properties.setValue("5:10pm", forKey: "时间")
self.properties.setValue("首页", forKey: "视频名称")   //属性名称不能超过255个字符,属性值不能超过200个字符

//记录事件
Zhuge.sharedInstance().track("观看视频", properties: self.properties as [NSObject : AnyObject])//事件名称不能超过32个字符

四、事件时长的统计

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


let zhuge = Zhuge()
let eventName = ""
zhuge.startTrack(eventName)

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

let zhuge = Zhuge()
let eventName = ""
let properties = NSMutableDictionary()
//定义与事件相关的属性信息
properties.setValue("xxx", forKey: "xxx")
zhuge.endTrack(eventName, properties: properties as? [AnyHashable : Any])

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

代码示例:

let zhuge = Zhuge()
let eventName = "观看视频"
zhuge.startTrack(eventName)
let properties = NSMutableDictionary()
//定义与事件相关的属性信息
properties.setValue("非诚勿扰", forKey: "名称")
properties.setValue("2016-11-02", forKey: "期数")
zhuge.endTrack(eventName, properties: properties as? [AnyHashable : Any])

*注意:startTrack与endTrack必须成对出现(eventName一致),单独调用一个接口是无效的。

五、设置事件通用属性

1. 事件通用属性

let properties = NSMutableDictionary()
Zhuge.sharedInstance().setSuperProperty((properties as? [AnyHashable : Any])!);

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

2. 设备自定义属性

let properties = NSMutableDictionary()
Zhuge.sharedInstance().setPlatform((properties as? [AnyHashable : Any])!);

六、其他可选API

Zhuge.sharedInstance().getDid()
您可以通过这个接口来获取当前设备在诸葛体系下的设备标识。
Zhuge.sharedInstance().getSid()
您可以通过这个接口来获得当前应用所属的会话ID

七、在UIWebView中进行统计

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

var webView = UIWebView.init()
weak var jsContext: JSContext?
    func webViewDidFinishLoad(_ webView: UIWebView) {

self.jsContext = webView.value(forKeyPath: "documentView.webView.mainFrame.javaScriptContext") as? JSContext
let model = ZhugeJS.init()
self.jsContext?.setObject(model, forKeyedSubscript: "zhugeTracker" as NSCopying & NSObjectProtocol)
self.jsContext!.exceptionHandler = 
    {(context, exception) in
        print("exception:", exception as Any) 

    }
}

JS代码统计参考JS集成文档

八、在WKWebView中进行统计

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

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

 let config = WKWebViewConfiguration.init()
let userContent = WKUserContentController.init()
userContent.add(ZhugeJS.init(), name: "zhugeTracker")
config.userContentController = userContent
let wkWebView = WKWebView.init(frame: self.view.frame, configuration: config)

JS代码集成

Native端配置好之后,即可在html页面中通过js进行移动端的打点。

JS事件统计代码示例:

参考JS集成文档

需要注意的是:JS端传递给移动端的数据必须依照固定的格式传递json对象,错误的格式会导致数据统计失败,一个格式完整的json对象如下:

  {        
  //此处的值为track 或者 identify。不可为其他的数据,否则会导致统计失败        
  //track代表这是一条事件统计的数据,用来埋点;identify代表这是一条标识用户的数据,用来标识用户      
    type:"track"或者"identify",        
    name :" 事件名称或者userID",//传递事件名称或者用户ID        
    prop : {//事件或者用户的属性,可以不传            
        "key1" : "value1",            
        "key2" : "value2",            
          ...      
           }    
  }

九、常见问题

1.诸葛io如何识别用户?

我们鼓励调用identify方法加入自己的用户ID(详见上文「识别用户」)。 诸葛io首选采用IDFA作为用户追踪的ID,这需要您的应用安装AdSupport依赖包。如果您的应用中没有广告,采用IDFA可能会审核被拒,请在编译时加入ZHUGE_NO_ADID标志,诸葛io将会采用 IDFV作为追踪的ID。

Xcode设置方法:

- Build Settings > Apple LLVM 6.0 - Preprocessing > Processor Macros > Release : ZHUGE_NO_ADID=1

coaPods设置方法: 选择Pods项目,TARGETS选择Zhugeio, 然后进行相应设置。 image

2.如何确认事件布点代码已正确编写?

你可以使用诸葛io的「实时调试」功能实时验证事件数据是否被诸葛io的服务器正确接收。在诸葛io统计初始化之前,调用如下代码,以开启实时调试:

var zhuge = Zhuge.sharedInstance()

//默认关闭打印 true打开
self.zhuge.config().debug = true

然后,进入诸葛io的「实时调试」页面,就可以实时观察到上传的数据。 注意:调试完成后请关闭debug。

3.兼容性与 ARC?

诸葛io SDK仅支持iOS 7.0以上系统,如果您的版本较低,强烈建议升级。 诸葛io SDK默认采用ARC,如果您的项目没有采用ARC,您需要在编译(Build Phases -> Compile Sources)时,为每个Zhuge文件标识为 -fobj-arc。

4.如何在xcode控制台查看诸葛io SDK输出的日志?

Xcode设置方法:

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

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

image

通过Pods方式导入的项目,查看日志需要在XCode中选择pods项目,然后在TARGETS中选择Zhugeio,再进行设置:Build Settings > Apple LLVM 7.0 - Preprocessing > Preprocessor Macros > Debug : ZHUGE_LOG=1

©zhugeio.com 京ICP备15049545号            文档更新时间 2019-04-18 10:24:10

results matching ""

    No results matching ""