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

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

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

1. 导入 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', '>=4.0.0'

end

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

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

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

兼容性和 ARC

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

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

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

1. 「command+n」选取 Header File

   

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

   

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

   

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

   

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

   

3. 初始化

3.1 获取 APPKEY 并添加基础配置

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

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

3.2 获取数据上送域名

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

saas 上报地址

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

基础配置

如果你需要修改 SDK 的默认设置，如设置版本渠道等，一定要在 startWithConfig 前执行

示例代码如下：

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(true)

   // 自定义渠道
   zhuge.config.channel = "My App Store" // 默认是@"App Store"
   // 开启内置事件上报（三项默认均为 false，需显式开启）
   zhuge.config.builtInEventConfig.enableAppStart = true
   zhuge.config.builtInEventConfig.enableAppEnd = true
   zhuge.config.builtInEventConfig.enableAppInstall = true // 开启后，trackAppInstall 接口才生效

   // 开启行为追踪
   zhuge.startWithConfig(zhuge.config, launchOptions: launchOptions)
   return true
}

隐私协议控制

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

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

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

客户同意隐私协议后，调用如下方法开启数据上报（在调用之前采集的数据会被缓存，调用后数据会上传）。

Zhuge.setPrivacyAgree(true)

开启日志

Zhuge.openLog()

开启数据上传加密

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

方式 1. 使用 CocoaPods 导入

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

pod 'ZhugeioAnalytics/GMEncrypt'

方式 2. 源码依赖

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

开启数据加密

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

Zhuge.sharedInstance().config.enableEncrypt = true

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

Zhuge.sharedInstance().config.encryptType = 2

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

pod "GMOpenSSL"

开启实时调试

你可以使用诸葛 io 提供的实时调试功能，实时监测数据是否正确上传，调试完成后请关闭 debug。

使用方法：在 SDK 初始化之前调用如下代码以开启实时调试，建议仅在测试设备上开启(true 为开始，false 为关闭)。

Zhuge.sharedInstance().config.debug = true

设置全局属性

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

let zhuge = Zhuge.sharedInstance()
let info = ["globalKey": "galobalValue"]
zhuge.setSuperProperty(info)

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

添加全局属性

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

let zhuge = Zhuge.sharedInstance()
let info = ["globalKey": "galobalValue"]
zhuge.addSuperProperty(info)

添加单个全局属性

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

let zhuge = Zhuge.sharedInstance()
zhuge.addSuperProperty(withKey: "key", value: "value")

删除单个全局属性

删除单个全局属性

let zhuge = Zhuge.sharedInstance()
zhuge.deleteSuperProperty(withKey: "key")

删除全部全局属性

删除全局属性

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

获取全局属性

获取当前生效的全局属性

let zhuge = Zhuge.sharedInstance()
let info = zhuge.getSuperproperties()

设置每日上传数量

为了节约用户流量，SDK 通过每日上传事件数量限制流量消耗，默认为 50000 事件。你可以根据需要调用如下接口设置该数量

Zhuge.sharedInstance().config.sendMaxSizePerDay = 50000

设置本地最大事件数

SDK 在数据上传到服务端之前，会在本地缓存用户的事件。以防止无网或者上传失败时数据丢失，但本地最大保存数量有限制，默认为 3000 条事件，你也可以调用如下接口自定义该数量

Zhuge.sharedInstance().config.cacheMaxSize = 3000

设置上报时间间隔

默认为 5 秒，设置单位为秒。

Zhuge.sharedInstance().config.sendInterval = 20

开启崩溃采集

在 SDK 初始化之前，调用如下代码开启崩溃采集功能。该功能开启之后，SDK 可以采集原生代码的部分崩溃信息，并上报到服务器。

Zhuge.sharedInstance().config.exceptionTrack = true

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

注: 如果你同时使用了 Bugly，可以兼容一起使用采集崩溃信息； 如果你同时使用了其他崩溃采集工具或自己采集，请测试兼容性； 如遇到问题，请随时联系我们。

开启全埋点采集

全埋点采集功能可以自动采集 PV 和按钮点击事件，要开启该功能，请在 SDK 初始化之前调用如下接口

Zhuge.sharedInstance().config.autoTrackEnable = true

全埋点采集默认采集数据:

$page_title：页面标题
$eid"：全埋点类型 click / pv
$element_content：控件的文本内容
$element_type：控件的类型
$element_selector：控件的选择器

全埋点高级控制 (通过关联对象动态绑定)

SDK 支持通过 Objective-C Runtime 的关联对象（Associated Objects）对特定 View 或 ViewController 进行精细化采集控制。

UIView (针对 Click 事件)

• zhugeioAttributesDonotTrack (Bool)：是否屏蔽该视图的点击追踪（全埋点黑名单）。
• zhugeioAttributesVariable ([String: Any])：为该视图绑定的自定义业务属性。

UIViewController (针对 PV/Click 事件)

• zhugeioAttributesPageName (String)：手动标识页面标题（影响 PV 事件名称）。
• zhugeioAttributesVariable ([String: Any])：为该页面下所有自动采集事件（pv/click）绑定的公共属性。

属性合并优先级 (由高到低)

当发生一次全埋点点击（Click）时，SDK 构建最终上报字典的合并逻辑如下：

1. View 自身属性：通过 view.zhugeioAttributesVariable 设置的属性。
2. 页面公共属性：通过 vc.zhugeioAttributesVariable 设置的属性。
3. 全局超级属性：通过 setSuperProperty: 设置的属性。

规则：同名 Key 冲突时，高优先级覆盖低优先级。

开启页面停留采集

页面停留采集可以自动统计用户在每个UIViewController的停留时长，要开启该功能，请在 SDK 初始化之前调用如下接口

Zhuge.sharedInstance().config.isEnableDurationOnPage = true

设置上传地址

私有部署客户可以通过该接口设置数据发送的服务器地址

let url = "https://example.com/apipool"
//获取config对象
let config = Zhuge.sharedInstance().config
config.setUploadURL(url, andBackupUrl: nil)

url 为服务器端数据采集接口所在路径，具体可以询问技术支持。 andBackupUrl 为主接口失效时的备份地址，没有可以为空，注意 url 需包含协议名称及路径。

设置设备 ID

SDK 默认采用 IDFV 作为设备 ID，如果你有自己的设备 ID 标识方案，可以在初始化时传入，作为设备 ID 使用

import UIKit

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        let zhuge = Zhuge.sharedInstance()
        let zhugeConfig = zhuge.config
        zhugeConfig.appKey = "Your App Key"
        zhuge.startWithConfig(zhugeConfig, andDid: "did", launchOptions: launchOptions)
        return true
    }
}

注意： 多实例初始化时，did 以第一个传入的为准，后续实例初始化传入 did 无效。

内嵌 H5 数据采集

sdk 支持 WKWebView 对应的内嵌 H5 数据采集功能，调用如下代码开启内嵌 H5 数据采集功能

Zhuge.sharedInstance().config.enableJavaScriptBridge = true

可视化采集

Zhuge.sharedInstance().config.enableVisualization = true

广告监测

诸葛支持采集苹果广告归因数据，如需使用，请在启动 sdk 之前调用如下接口，诸葛会在应用启动时尝试获取应用的归因信息。

3.3 内置事件

SDK 支持自动或手动采集核心业务指标（appStart、appEnd、appInstall），默认关闭。

应用启动 (appStart)

• 触发逻辑：监听应用进入前台通知（兼容 iOS 13+ Scene 模式）。
• 采集属性：$resume_from_background (是否热启动)、$ct (触发时间戳)。
• 开启方式：zhuge.sharedInstance().config.builtInEventConfig.enableAppStart = true

应用退出 (appEnd)

• 触发逻辑：监听应用退入后台通知。
• 时长计算：自动计算本次前台停留时长 $event_duration（单位：毫秒）。
• 开启方式：zhuge.sharedInstance().config.builtInEventConfig.enableAppEnd = true
• 后台任务：SDK 会自动申请后台执行时间，确保 appEnd 事件及队列数据能成功上报。

应用安装 (appInstall)

• 触发逻辑：需手动调用 trackAppInstall: 接口触发。
• 幂等保护：SDK 内部会进行去重保护，同一 AppKey 下仅上报一次。
• 支持参数：接口仅处理如下白名单内的 Key：
  • utm_source: 广告来源
  • utm_medium: 广告媒介
  • utm_campaign: 广告名称
  • utm_content: 广告内容
  • utm_term: 广告关键词
  • browser: 浏览器信息
• 示例代码：

  Zhuge.sharedInstance().trackAppInstall(["utm_source": "App Store", "utm_medium": "cpc"])
  

• 开启方式：zhuge.sharedInstance().config.builtInEventConfig.enableAppInstall = true（必须开启此开关，接口才生效）。

4. 识别用户

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

Zhuge.sharedInstance().identify(userId, properties: userInfo)

参数说明：

代码示例:

//定义诸葛io中的用户ID
let userId = user.getUserId()

//定义属性
var userInfo: [String: Any] = [:]
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 个字符计算。

5. 自定义事件

你可以在 startWithConfig 之后开始记录事件（用户行为），并可记录与该事件相关的属性信息

//定义与事件相关的属性信息
var properties: [String: Any] = [:]
properties["分类"] = "手机"
properties["型号"] = "iPhone6 plus 64g"
properties["价格"] = 5888 //数值型属性不要带引号
//记录事件
Zhuge.sharedInstance().track("购买", properties: properties)

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

6. 事件时长统计

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

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

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

let zhuge = Zhuge.sharedInstance()
let eventName = ""
let pro: [String: Any] = [:]
zhuge.endTrack(eventName, properties: pro)

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

代码示例：

let zhuge = Zhuge.sharedInstance()
let eventName = "观看视频"

//视频播放开始
zhuge.startTrack(eventName)

//视频观看结束
var pro: [String: Any] = [:]
pro["名称"] = "非诚勿扰"
pro["期数"] = "2016-11-02"
zhuge.endTrack(eventName, properties: pro)

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

7. 设置自定义属性

事件自定义属性

let zhuge = Zhuge.sharedInstance()
zhuge.setSuperProperty(pro)

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

8. 在 WKWebView 中进行统计

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

• Swift 代码集成

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

import WebKit

//初始化一个WKWebViewConfiguration
let config = WKWebViewConfiguration()

//初始化一个WKUserContentController
let userContent = WKUserContentController()

//给WKUserContentController设置一个js脚本控制器
userContent.add(ZhugeJS(), name: "zhugeTracker")

//将配置过脚本控制器的WKUserContentController设置给WKWebViewConfiguration
config.userContentController = userContent

//使用配置好的WKWebViewConfiguration，创建WKWebView
self.webView = WKWebView(frame: frame, configuration: config)

// 配置UserAgent
self.webView.evaluateJavaScript("navigator.userAgent") { [weak self] (result, error) in
    if error == nil, let userAgent = result as? String {
        let newUserAgent = userAgent + " ZGSDK"
        let dictionary = ["UserAgent": newUserAgent]
        UserDefaults.standard.register(defaults: dictionary)
    } else {
        print("设置ZGUserAgent失败 == \(error?.localizedDescription ?? "")")
    }
}

也可以交给诸葛进行自动打通 H5，请在初始化之前调用如下方法：

Zhuge.sharedInstance().config.enableJavaScriptBridge = true

• JS 代码集成

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

9. 元素曝光采集

曝光采集功能默认关闭，需要在 SDK 调用 start 之前进行开启

Zhuge.sharedInstance().config.isEnableExpTrack = true

标记需要曝光采集的元素，一般而言，在 view 初始化之后调用如下方法进行标记

button.zhugeioExpTrack("your event id")

zhugeioExpTrack 参数说明

1、追踪 UIButton 代码示例:

button = UIButton(frame: CGRect(x: 20, y: 250, width: 100, height: 35))
button.setTitle("Button", for: .normal)
button.zhugeioExpTrack("your event id", withVariable: ["tempkey0": "tempvalue0"])

2、追踪列表某一行

func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
    let item = collectionView.dequeueReusableCell(withReuseIdentifier: "ImageCell", for: indexPath) as! XSImageCell

    if indexPath.item == 0 {
        item.zhugeioExpTrack("your event id")
    } else {
        item.zhugeioStopExpTrack()
    }

    return item
}

3、追踪列表全部行

func collectionView(_ collectionView: UICollectionView, cellForItemAt indexPath: IndexPath) -> UICollectionViewCell {
    let item = collectionView.dequeueReusableCell(withReuseIdentifier: "ImageCell", for: indexPath) as! XSImageCell

    item.zhugeioExpTrack("your event id")

    return item
}

其他可选 API

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

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

隐私政策说明

• SDK隐私政策：诸葛IO SDK隐私政策（iOS版）
• 开发者使用合规规范：诸葛IO SDK（iOS版）开发者合规使用指南

更新说明

• SDK名称：诸葛IO SDK
• SDK开发者：北京诸葛云游科技有限公司
• 主要功能：支持采集基础数据，用于对应用的新增、激活、留存等统计性指标进行分析。

v4.3.3

更新时间: 2026-05-08

SDK - 下载地址: SDK - 不含国密版（标准版）
国密 - 下载地址: 下载国密部分代码

• 重要：从此版本开始，iOS 12.0 以下系统不再支持
• 新增：内置事件appStart、appEnd、appInstall
• 新增：全埋点页面公共属性（支持在ViewController中添加属性，当页面中的按钮触发点击时，自动添加对应属性到全埋点click事件中）
• 新增：全埋点元素黑名单（支持用户指定不需要进行全埋点的元素。被标记的元素触发点击时，将不进行点击采集）

v4.3.2

更新时间: 2026-03-20

SDK - 下载地址: SDK - 不含国密版（标准版）
国密 - 下载地址: 下载国密部分代码

• 修复：可视化埋点识别元素异常问题修复

v4.3.1

更新时间: 2026-03-18

下载地址: SDK - 不含国密版（标准版）

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