iOS Swift SDK (v4.0.0 以上版本)

集成 4.0 之前版本请参考 3.*版本集成文档

重要提示！
升级到 v4.3.0 版本需要注意：v4.3.0 版本不包含国密加密，若你需要使用国密算法来加密数据。请查看[开启数据上传加密]章节的介绍

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', '>=4.0.0'

end

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

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

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

1.2 导入国密部分代码

默认 sdk 中不包含国密加密，若你需要使用国密算法来加密数据。需根据不同导入方式增加下列内容：

方式 1. 使用 CocoaPods 导入

若你使用 CocoaPods 来导入诸葛，请添加国密部分代码。

pod  'ZhugeioAnalytics/GMEncrypt'

方式 2. 源码依赖

若你选择下载源码引入的方式，将下载国密部分代码，添加到项目中。并安装依赖 Security，另外还需引入 pod 库：GMOpenSSL。

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

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

「command+n」选取 Header File
注意头文件名字的命名规范：项目名称-Brdging-Header.h，如下图:
新建完成后，使用＃import 来引用 oc 库，如下图:
该步骤比较重要，选择 SexyGallery > Build Settings > 在搜索框输入 "Swift Compiler" > 双击 Objective-C Bridging Header > 直接把刚才的 Header.h 从工程拖入进来会生成这个文件的路径。
之后我们就可以愉快在工程里调用第三方类库编写代码了。

3. 初始化

3.1 开启数据上传加密

默认 sdk 中不包含国密加密，若你需要使用国密算法来加密数据。需根据不同导入方式增加下列内容：

方式 1. 使用 CocoaPods 导入

若你使用 CocoaPods 来导入诸葛，请添加国密部分代码。

pod  'ZhugeioAnalytics/GMEncrypt'

方式 2. 源码依赖

若你选择下载源码引入的方式，将下载国密部分代码，添加到项目中。并安装依赖 Security，另外还需引入 pod 库：GMOpenSSL。

开启数据加密

SDK 的数据上传时进行了编码，若您有数据加密需求，可以调用如下接口开启数据加密传输

Zhuge.sharedInstance().config().enableEncrypt = YES;

默认的加密算法是 RSA+AES，可通过以下方式改为国密（1 为 rsa+aes，2 为国密）

Zhuge.sharedInstance().config().encryptType = 2

使用国密需要下载国密版的包，同时在应用中引入 GMOpenSSL，可通过 pod 引入

pod "GMOpenSSL"

3.2 获取 APPKEY 并添加基础配置

在开始集成前，首先拥有一个应用/主体，进行 SDK 集成前，您需要获取对应应用/主体的 App Key 信息。

您可以在「应用管理」->「主体管理」->「设置」中可查看您的 App Key

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

import ZhugeioAnalytics

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

   // 实时调试开关: 生产环境禁止开启，仅用于研发调试环境
   // zhuge.config().debug = true

   // 隐私协议控制: 不添加该配置，隐私协议控制默认是关闭的；如果添加该配置，请务必查看下面的【隐私协议控制】章节，若您是新应用集成，则需描述为 YES
   zhuge.setPrivacyControl(YES);

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

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

   return true
}

3.3 获取数据上送域名

私有化部署版本需要获取数据上送域名。如您不清楚此域名，请联系您的项目经理或技术支持。

saas 上报地址

首选上报地址：https://su.zhugeio.com/apipool
备用上报地址：https://subak.zhugeio.com/apipool

3.4 隐私协议控制

诸葛 sdk 默认情况下，初始化之后即可开始上传数据。若你的应用需要根据用户的隐私协议状态来决定是否上传数据。你有两种方式来处理诸葛的数据上传。

根据用户的隐私协议状态来决定是否初始化诸葛 sdk。你可以在用户同意隐私协议之后再初始化诸葛 sdk。但要注意，sdk 初始化之前不可调用 sdk 的任何数据接口(如 track、indetify 等)。
使用诸葛 sdk 的隐私协议控制。在诸葛 sdk 初始化之前，调用如下代码告诉诸葛 sdk 来启用隐私协议控制。

Zhuge.setPrivacyControl(YES); // 启动隐私协议控制（不添加该配置，隐私协议控制默认是关闭的）

客户同意隐私协议后，调用如下方法，调用后产生的数据正常上传，在调用之前采集的数据不会被上报。

Zhuge.setPrivacyControl(YES);

4.全局属性

4.1 设置全局属性

如果有一些属性是你想在所有的自定义事件中携带，可调用如下接口设置全局属性，设置完毕之后，后续的事件都会携带这些属性。

let zhuge = Zhuge.sharedInstance()
let info: [String: Any] = ["globalKey": "globalValue"]
zhuge.setSuperProperty(info)

重复调用该接口会以最后一次调用的为准。若事件中有相同名称的属性，以事件中的为准。

4.2 添加全局属性

添加全局属性，会合并到之前的全局属性中

let zhuge = Zhuge.sharedInstance()
let info: [String: Any] = ["globalKey": "globalValue"]
zhuge.addSuperProperty(info)

4.3 添加单个全局属性

添加单个全局属性，会合并到之前的全局属性中

let zhuge = Zhuge.sharedInstance()
zhuge.addSuperProperty(with: "globalKey", value: "globalValue")

4.4 删除单个全局属性

删除单个全局属性

let zhuge = Zhuge.sharedInstance()
zhuge.deleteSuperProperty(with: "globalKey")

4.5 删除全部全局属性

删除全局属性

let zhuge = Zhuge.sharedInstance()
zhuge.clearSuperProperty()

4.6 获取全局属性

获取当前生效的全局属性

let zhuge = Zhuge.sharedInstance()
let properties = zhuge.getSuperProperties()

5. 识别用户

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

6. 自定义事件

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

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

7. 事件时长的统计

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


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

8. 设置事件通用属性

8.1 事件通用属性

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

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

8.2 设备自定义属性

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

9. 其他可选 API

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

10. 在 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",
          ...
           }
  }

11. 常见问题

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

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

var zhuge = Zhuge.sharedInstance()

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

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

11.2 兼容性与 ARC？

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

11.3 如何在 xcode 控制台查看诸葛 io SDK 输出的日志？

要在 xcode 控制台查看诸葛 io SDK 输入的日志，请在初始化前，调用如下代码

Zhuge.openLog();

更新说明

v4.3.0

更新时间: 2025-12-24

新增：隐私协议选项，不同意时不上传数据，默认上传（包含崩溃事件）
新增：应用进入后台时的数据上传（进入后台时尝试上传，等任务结束再缓存数据）
修复：会话变更设计与 android 和鸿蒙一致，30 秒后进入应用时触发会话结束
修复：多主体崩溃采集存在的问题
修复：当 button 绑定有多个点击时，全埋点会多次触发的问题
修复：应用有系统弹窗时的会话事件生成(之前系统弹窗会导致 ss 与 se，现在不会)
- 30 秒内点击系统弹窗确认，不触发会话事件（还在同一个会话）
- 大于 30 秒，触发会话结束会话开始事件（开启新会话）

v4.1.0

更新时间: 2025-10-12

新增：添加设置全局属性方法
修复：自定义事件优先使用自身属性，之前版本自身属性会被全局属性覆盖
修复：国密命名冲突修复

v4.0.1

更新时间: 2025-05-26

破坏性升级

添加多主体上报模式，初始化 Api 修改

iOS Swift SDK (v4.0.0 以上版本)

1. 导入 SDK

方法 1. 使用CocoaPods导入

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

1.2 导入国密部分代码

方式 1. 使用 CocoaPods 导入

方式 2. 源码依赖

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

3. 初始化

3.1 开启数据上传加密

方式 1. 使用 CocoaPods 导入

方式 2. 源码依赖

开启数据加密

3.2 获取 APPKEY 并添加基础配置

3.3 获取数据上送域名

3.4 隐私协议控制

4.全局属性

4.1 设置全局属性

4.2 添加全局属性

4.3 添加单个全局属性

4.4 删除单个全局属性

4.5 删除全部全局属性

4.6 获取全局属性

5. 识别用户

6. 自定义事件

7. 事件时长的统计

8. 设置事件通用属性

8.1 事件通用属性

8.2 设备自定义属性

9. 其他可选 API

10. 在 WKWebView 中进行统计

JS 代码集成

JS 事件统计代码示例：

11. 常见问题

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

11.2 兼容性与 ARC？

11.3 如何在 xcode 控制台查看诸葛 io SDK 输出的日志？

更新说明

v4.3.0

v4.1.0

v4.0.1

results matching ""

No results matching ""