Skip to content

BuglyDevTeam/Bugly-iOS

Repository files navigation

Bugly iOS SDK 接入指南

一. SDK 集成

Bugly提供两种集成方式供iOS开发者选择:

  • CocoaPods
  • 手动集成

如果您是从Bugly 2.0以下版本升级过来的,请查看 Bugly 旧版本顺滑升级指引

1.1 CocoaPods集成方式

命令行下执行pod search Bugly,如显示的Bugly版本不是最新的,则先执行pod repo update操作

在工程的Podfile里面添加以下代码:

pod 'Bugly'

保存并执行pod install,然后用后缀为.xcworkspace的文件打开工程。

关于CocoaPods的更多信息请查看CocoaPods官方网站

1.2 手动集成方式

  • 下载并解压iOS SDK
  • 拖拽Bugly.framework文件到Xcode工程内(请勾选Copy items if needed选项)
  • 添加依赖库
    • SystemConfiguration.framework
    • Security.framework
    • libz.dylib

二. 初始化SDK

2.1 导入头文件

在工程的AppDelegate.m文件导入头文件

#import <Bugly/Bugly.h>

如果是Swift工程,请在对应bridging-header.h中导入

2.2 初始化Bugly

在工程AppDelegate.mapplication:didFinishLaunchingWithOptions:方法中初始化Bugly:

  • Objective-C
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	[Bugly startWithAppId:@"此处替换为你的AppId"];
	return YES;
}
  • Swift
func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: [NSObject: AnyObject]?) -> Bool {
	Bugly.startWithAppId("此处替换为你的AppId")
	return true
}

如果您需要上报iOS Watch2 AppiOS App Extension的异常,请参见Bugly iOS Extension SDK 接入指南

至此,Xcode工程集成Bugly已完成,接下来可以编译并运行你的Xcode工程。

三. 高级功能

Bugly SDK提供一系列自定义配置或接口供开发者调用,如:

  • 文件配置初始化参数
  • 自定义日志
  • 界面追踪
  • 卡顿监控

详细内容请查看iOS SDK高级设置


Bugly iOS SDK高级功能使用指南

一. 文件配置初始化参数

Bugly支持读取Info.plist文件读取SDK初始化参数,可配置的参数如下:

- Appid
	- Key: BuglyAppIDString
	- Value: 字符串类型
- 渠道标识
	- Key: BuglyAppChannelString
	- Value: 字符串类型
- 版本信息
	- Key: BuglyAppVersionString
	- Value: 字符串类型
- 开启Debug信息显示
	- Key: BuglyDebugEnable
	- Value: BOOL类型

如下初始化方式,则会读取Info.plist内添加的key-value配置进行SDK初始化:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
	// 读取Info.plist中的参数初始化SDK
	[Bugly startWithAppId:nil];
	return YES;
}

二. 自定义日志

SDK提供自定义日志打印接口,用于记录一些关键的业务调试信息,可以更全面地反应App发生崩溃或异常时的上下文环境。

使用方式与NSLog一致,可定义日志级别以便过滤,日志接口宏定义如下:

BLYLogError(fmt, ...)
BLYLogWarn(fmt, ...)
BLYLogInfo(fmt, ...)
BLYLogDebug(fmt, ...)
BLYLogVerbose(fmt, ...)

void BLYLog(BuglyLogLevel level, NSString *format, ...);
void BLYLogv(BuglyLogLevel level, NSString *format, va_list args);

三. 接口声明

1. 功能配置

/**
 *  SDK Debug 信息开关, 默认关闭
 */
@property (nonatomic, assign) BOOL debugMode;

/**
 *  设置自定义渠道标识
 */
@property (nonatomic, copy) NSString *channel;

/**
 *  设置自定义版本号
 */
@property (nonatomic, copy) NSString *version;

/**
 *  设置自定义设备唯一标识
 */
@property (nonatomic, copy) NSString *deviceId;

/**
 *  卡顿监控开关,默认关闭
 */
@property (nonatomic, assign) BOOL blockMonitorEnable;

/**
 *  卡顿监控判断间隔,单位为秒
 */
@property (nonatomic, assign) NSTimeInterval blockMonitorTimeout;

/**
 *  ATS开关,默认开启。如果关闭,SDK的网络请求不会通过HTTPS发送
 */
@property (nonatomic) BOOL appTransportSecurityEnable;

/**
 *  进程内还原开关,默认开启。
 */
@property (nonatomic) BOOL symbolicateInProcessEnable;

/**
 *  非正常退出事件记录开关,默认关闭
 */
@property (nonatomic) BOOL unexpectedTerminatingDetectionEnable;

/**
 *  页面信息记录开关,默认开启
 */
@property (nonatomic) BOOL viewControllerTrackingEnable;

/**
 *  SDK回调
 */
@property (nonatomic, assign) id<BuglyDelegate> delegate;

/**
 * 控制自定义日志上报,默认值为BuglyLogLevelWarn,只上报Warn、Error的日志。
 * 设置为BuglyLogLevelSilent可关闭日志上报。
 */
@property (nonatomic, assign) BuglyLogLevel reportLogLevel;

2. SDK回调

/**
 *  发生异常时回调
 *
 *  @param exception 异常信息
 *
 *  @return 返回需上报记录,随异常上报一起上报
 */
- (NSString *)attachmentForException:(NSException *)exception;

3. 功能接口

/**
 *  初始化Bugly,使用默认BuglyConfig
 *
 *  @param appId 注册Bugly分配的应用唯一标识,如果appId为空,则读取Info.plist中的参数配置
 */
+ (void)startWithAppId:(nullable NSString *)appId;

/**
 *  使用指定配置初始化Bugly
 *
 *  @param appId 注册Bugly分配的应用唯一标识
 *  @param config 传入配置的 BuglyConfig
 */
+ (void)startWithAppId:(nullable NSString *)appId
                config:(nullable BuglyConfig *)config;

/**
 *  设置用户标识
 *
 *  @param userId 用户标识
 */
+ (void)setUserIdentifier:(nonnull NSString *)userId;

/**
 *  更新应用版本信息
 *
 *  @param version 应用版本信息
 */
+ (void)updateAppVersion:(NSString *)version;

/**
 *  设置关键数据,随崩溃信息上报
 *
 *  @param value
 *  @param key
 */
+ (void)setUserValue:(nonnull NSString *)value
              forKey:(nonnull NSString *)key;

/**
 *  获取关键数据
 *
 *  @return 关键数据
 */
+ (nullable NSDictionary *)allUserValues;

/**
 *  设置标签
 *
 *  @param tag 标签ID,可在网站生成
 */
+ (void)setTag:(NSUInteger)tag;

/**
 *  获取当前设置标签
 *
 *  @return 当前标签ID
 */
+ (NSUInteger)currentTag;

/**
 *  上报自定义异常
 *
 *  @param exception 异常信息
 */
+ (void)reportException:(nonnull NSException *)exception;

/**
 *  上报错误
 *
 *  @param error 错误信息
 */
+ (void)reportError:(NSError *)error;

/**
 *  SDK 版本信息
 *
 *  @return
 */
+ (nonnull NSString *)sdkVersion;

/**
 *  获取设备ID
 *
 *  @return 设备ID
 */
+ (nonnull NSString *)deviceId;