登录
目录
当前位置： 首页 > 文档资料 > 诸葛 io 帮助文档 >

iOS Swift SDK

优质
小牛编辑
130浏览
2023-12-01

1. 安装诸葛io SDK

通过CocoaPods安装：

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

你也可以选择手动导入：

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

1.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

1.2. 初始化SDK

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

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

import ZhugeioAnalytics

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
    }

2. 识别用户

为了保持对用户的跟踪，你需要为每一位用户记录一个唯一的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: "孩子的性别")

3. 自定义事件

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

////定义与事件相关的属性信息  
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个字符

4. 事件时长的统计

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


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

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

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

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

代码示例：

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

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

5. 设置事件通用属性

5.1. 事件通用属性

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

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

5.2. 设备自定义属性

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

6. 其他可选API

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

7. 在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)

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

  Zhuge.sharedInstance().config().enableJavaScriptBridge = true;

JS代码集成

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

JS事件统计代码示例：

参考Web 集成开发指南

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

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

8. 常见问题

8.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

8.2. 如何确认事件布点代码已正确编写？

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

var zhuge = Zhuge.sharedInstance()

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

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

8.3. 兼容性与 ARC？

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

8.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

免责声明： 以上内容版权归原作者所有，如有侵犯您的原创版权请告知，我们将尽快删除相关内容。感谢每一位辛勤著写的作者，感谢每一位的分享。
@小牛知识库 xnip.cn