iOS Objective-C 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;

2. 兼容性和 ARC

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

3. 初始化

3.1 获取 APPKEY

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

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

3.2 获取数据上送域名

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

saas 上报地址

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

3.3 初始化 SDK

将 SDK 的初始化代码放入 Application 类中

#import "Zhuge.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Zhuge *zhuge = [Zhuge sharedInstance];
    ZhugeConfig *zhugeConfig = zhuge.config;
    zhugeConfig.appKey = @"Your App Key";
    [zhuge startWithConfig:zhugeConfig launchOptions:launchOptions];
}

多实例初始化：如果应用需要使用多个实例进行初始化，请调用newInstance来获取一个新的诸葛 io 实例，然后对该实例进行上述初始化操作

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Zhuge *zhuge = [Zhuge newInstance];
    ZhugeConfig *secondConfig = zhuge.config;
    secondConfig.appKey = @"zhugeio-appkey";
    [zhuge startWithConfig:secondConfig launchOptions:launchOptions];
}

基础配置

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

示例代码如下：

Zhuge *zhuge = [Zhuge sharedInstance];
ZhugeConfig *zhugeConfig = zhuge.config;

// 实时调试开关: 生产环境禁止开启，仅用于研发调试环境
// [Zhuge sharedInstance].config.debug=YES;

// debug开关: 生产环境禁止开启，仅用于研发调试环境
// [zhugeConfig setDebug : YES];

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

// 自定义应用版本
[zhugeConfig setAppVersion:@"0.9-beta"]; // 默认是info.plist中CFBundleShortVersionString值

// 自定义渠道
[zhugeConfig setChannel:@"My App Store"]; // 默认是@"App Store"

// 开启行为追踪
[zhuge startWithConfig:zhugeConfig launchOptions:launchOptions];

隐私协议控制

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

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

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

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

[Zhuge setPrivacyAgree:YES];

开启日志

[Zhuge openLog];

开启数据上传加密

默认 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"

开启实时调试

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

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

[Zhuge sharedInstance].config.debug=YES;

设置全局属性

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

Zhuge *zhuge = [Zhuge sharedInstance];
NSDictionary *info = @{@"globalKey":@"galobalValue"};
[zhuge setSuperProperty:(NSDictionary *) info];

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

添加全局属性

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

Zhuge *zhuge = [Zhuge sharedInstance];
NSDictionary *info = @{@"globalKey":@"galobalValue"};
[zhuge addSuperProperty:(NSDictionary *) info];

添加单个全局属性

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

Zhuge *zhuge = [Zhuge sharedInstance];
[zhuge addSuperPropertyWithKey:(NSString *) key value:(NSString *)value];

删除单个全局属性

Zhuge *zhuge = [Zhuge sharedInstance];
[zhuge deleteSuperPropertyWithKey:(NSString *) key];

删除全部全局属性

删除全局属性

Zhuge *zhuge = [Zhuge sharedInstance];
[zhuge clearSuperProperty];

获取全局属性

获取当前生效的全局属性

Zhuge *zhuge = [Zhuge sharedInstance];
NSDictionary *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 = YES;

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

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

开启全埋点采集

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

[Zhuge sharedInstance].config.autoTrackEnable = YES;

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

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

开启页面停留采集

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

[Zhuge sharedInstance].config.isEnableDurationOnPage = YES;

设置上传地址

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

NSString url = @"https://example.com/apipool";
//获取config对象
ZhugeConfig *config = [Zhuge sharedInstance].config;
[config setUploadURL:url andBackupUrl:nil];

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

设置设备 ID

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

#import "Zhuge.h"

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    Zhuge *zhuge = [Zhuge sharedInstance];
    ZhugeConfig *zhugeConfig = zhuge.config;
    zhugeConfig.appKey = @"Your App Key";
    [zhuge startWithConfig:zhugeConfig andDid:@"did" launchOptions:launchOptions];
}

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

内嵌 H5 数据采集

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

[Zhuge sharedInstance].config.enableJavaScriptBridge = YES;

可视化采集

[Zhuge sharedInstance].config.enableVisualization = YES;

广告监测

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

[Zhuge enableIDFACollect];

开启后会采集 IDFA 信息，若要停止采集，则关闭初始化调用即可。

4. 识别用户

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

[[Zhuge sharedInstance] identify:userId properties:userInfo];

参数说明：

参数名称	说明
userId	业务系统用户唯一标识
userInfo	用户属性

代码示例:

//定义诸葛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 个字符计算。

5. 自定义事件

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

//定义与事件相关的属性信息
NSMutableDictionary *properties = [NSMutableDictionary dictionary];
properties[@"分类"] = @"手机";
properties[@"型号"] = @"iPhone6 plus 64g";
properties[@"价格"] = @5888;//数值型属性不要带引号
//记录事件
[[Zhuge sharedInstance] track:@"购买" properties: properties];

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

6. 事件时长统计

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

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

7. 设置自定义属性

事件自定义属性

Zhuge *zhuge = [Zhuge sharedInstance];
[zhuge setSuperProperty:(NSDictionary *) pro];

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

8. 在 WKWebView 中进行统计

如果你的页面中使用了 WKWebView 嵌入 HTML、JavaScript 的代码，并且希望统计 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];

// 配置UserAgent
__block NSString *newUserAgent_WK;
__block NSDictionary *dictionary;
[self.webView evaluateJavaScript:@"navigator.userAgent" completionHandler:^(id result, NSError *error) {
if (!error) {
    newUserAgent_WK = [result stringByAppendingString:@" ZGSDK"];
    dictionary = [NSDictionary dictionaryWithObjectsAndKeys:newUserAgent_WK, @"UserAgent", nil];
    [[NSUserDefaults standardUserDefaults] registerDefaults:dictionary];
} else {
    NSLog(@"设置ZGUserAgent失败 == %@",error);
}
}];

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

[Zhuge sharedInstance].config.enableJavaScriptBridge = YES;

JS 代码集成

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

9. 元素曝光采集

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

[Zhuge sharedInstance].config.isEnableExpTrack = YES;

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

[self.button zhugeioExpTrack:@"your event id"];

zhugeioExpTrack 参数说明

参数名称	是否必须	说明
eventId	必须	事件名称
variable	非必须	曝光时对应的事件属性

1、追踪 UIButton 代码示例:

self.button = [[UIButton alloc] initWithFrame:CGRectMake(20, 250, 100, 35)];
[self.button setTitle:@"Button" forState:UIControlStateNormal];
[self.button zhugeioExpTrack:@"your event id" withVariable:@{@"tempkey0":@"tempvalue0"}];

2、追踪列表某一行

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    XSImageCell *item = [collectionView dequeueReusableCellWithReuseIdentifier:@"ImageCell" forIndexPath:indexPath];

    if (indexPath.item == 0) {
        [item zhugeioExpTrack:@"your evnet id"];
    } else {
        [item zhugeioStopExpTrack];
    }

    return item;
}

3、追踪列表全部行

- (UICollectionViewCell *)collectionView:(UICollectionView *)collectionView cellForItemAtIndexPath:(NSIndexPath *)indexPath {
    XSImageCell *item = [collectionView dequeueReusableCellWithReuseIdentifier:@"ImageCell" forIndexPath:indexPath];

    [item zhugeioExpTrack:@"your evnet id"];

    return item;
}

其他可选 API

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

隐私政策说明

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

更新说明

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

v4.3.0

更新时间: 2025-12-24

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

v4.1.0

更新时间: 2025-10-12

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

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

v4.0.1

更新时间: 2025-05-26

破坏性升级

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